--- name: "proc" section: "3" platform: "macos" package: "ksh" version: "42" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/proc" --- # proc(3) process control routines ## NAME proc - process control routines ## SYNOPSIS ``` #include Proc_t* procopen(const char* command, char** argv, char** envv, long* opv, long flags); int procfree(Proc_t* proc); int procclose(Proc_t* proc); int procrun(const char* command, char** argv); ``` ## DESCRIPTION *These routines provide a portable interface to process creation and execution.* *They work on systems with* [*fork*(2)](/fork/2.md) *and* *exec*(2) *as well as on systems with only* *spawnve*(2) *or* *spanwveg*(3). $1$2procopenprocopenprocopenprocopenprocopenprocopenprocopenprocopen runs *command* with arguments *argv*, environment modifications in *envv*, file descriptor, signal and process group operations in *opv* and flags in *flags*. *command* is searched for using the $1$2PATHPATHPATHPATHPATHPATHPATHPATH environment variable from the calling environment. If *command* is $1$200000000 then the current shell is used (see *pathshell*(3)). If *envv* is not $1$200000000 then it is a $1$200000000 terminated vector of *name*\[=*value*\] strings that are added to the *command* environment using [*setenviron*(3)](/setenviron/3.md). If *name* appears in the parent environment then its value is replaced with the new *value*. If =*value* is omitted then *name* is removed from the child environment. The $1$2\_\_\_\_\_\_\_\_ environment variable is set to contain the pathname for *command* and will appear at the top of the child environment. If *opv* is not $1$200000000 then it is a 0 terminaled vector of operations to perform. In the following *context* is a combination of $1$2PROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILDPROC\_FD\_CHILD and $1$2PROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENTPROC\_FD\_PARENT for the child and parent process context respectively. Valid operations are: - PROC\_FD\_CLOSE(*fd*,*context*) The file descriptor *fd* is closed in *context*. - PROC\_FD\_DUP(*from*,*to*,*context*) The file descriptor *from* is [*dup*(2)](/dup/2.md)'d into the file descriptor *to* in *context*. - PROC\_SIG\_DFL(*sig*) The signal handler for *sig* is set to $1$2SIG\_DFLSIG\_DFLSIG\_DFLSIG\_DFLSIG\_DFLSIG\_DFLSIG\_DFLSIG\_DFL in the child context. - PROC\_SIG\_IGN(*sig*) The signal handler for *sig* is set to $1$2SIG\_IGNSIG\_IGNSIG\_IGNSIG\_IGNSIG\_IGNSIG\_IGNSIG\_IGNSIG\_IGN in the child context. - PROC\_SYS\_PGRP(*pgid*) The child process group is set to *pgid*. *pgid* may have the following values: - $1$2\<0\<0\<0\<0\<0\<0\<0\<0 The child process becomes a session leader. - $1$200000000 The child process is in the parent process group. - $1$211111111 The child process becomes a process group leader. - $1$2\>1\>1\>1\>1\>1\>1\>1\>1 The child process joins the process group *pgid*. - PROC\_SYS\_UMASK(*mask*) The child process group file creation mask is set to *mask*. *flags* is the inclusive-or of the following: - $1$2PROC\_ARGMODPROC\_ARGMODPROC\_ARGMODPROC\_ARGMODPROC\_ARGMODPROC\_ARGMODPROC\_ARGMODPROC\_ARGMOD *argv\[-1\]* and *argv\[0\]* may be modified. This is an optimization that avoids an environment vector *[realloc(3)](/realloc/3.md)* when *command* is a shell script. - $1$2PROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUNDPROC\_BACKGROUND Standard shell $1$2&&&&&&&& setup is done for the child process. - $1$2PROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUPPROC\_CLEANUP Parent process redirection file discriptors are closed on error. - $1$2PROC\_DAEMONPROC\_DAEMONPROC\_DAEMONPROC\_DAEMONPROC\_DAEMONPROC\_DAEMONPROC\_DAEMONPROC\_DAEMON Standard daemon setup is done for the child process. - $1$2PROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEARPROC\_ENVCLEAR The child environment is cleared before *envv* is added. - $1$2PROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GID The child effective group id is set to the real group id. - $1$2PROC\_IGNOREPROC\_IGNOREPROC\_IGNOREPROC\_IGNOREPROC\_IGNOREPROC\_IGNOREPROC\_IGNOREPROC\_IGNORE Parent pipe errors are ignored. - $1$2PROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAYPROC\_OVERLAY The current process is overlayed by *command* if possible (i.e., the [*fork*(2)](/fork/2.md) call is omitted). - $1$2PROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOIDPROC\_PARANOID Paranoid: *command* is searched using the default standard $1$2PATHPATHPATHPATHPATHPATHPATHPATH the child environment variable $1$2PATHPATHPATHPATHPATHPATHPATHPATH is set to the default standard; the $1$2PROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GIDPROC\_GID and $1$2PROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UID modes are set; only $1$2/bin/sh/bin/sh/bin/sh/bin/sh/bin/sh/bin/sh/bin/sh/bin/sh is used to execute *command* if it is a shell script. - $1$2PROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGEDPROC\_PRIVELEGED If the effective user id is $1$200000000 then the child real user id is set to $1$200000000 and the child real group id is set to the effective group id. - $1$2PROC\_READPROC\_READPROC\_READPROC\_READPROC\_READPROC\_READPROC\_READPROC\_READ *proc.rfd* is connected to *command*'s standard output. - $1$2PROC\_SESSIONPROC\_SESSIONPROC\_SESSIONPROC\_SESSIONPROC\_SESSIONPROC\_SESSIONPROC\_SESSIONPROC\_SESSION The child process becomes a session group leader. (Equivalent to the *opv* entry $1$2PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1)PROC\_SYS\_PGRP(-1) - $1$2PROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UIDPROC\_UID The child effective user id is set to the real user id. - $1$2PROC\_WRITEPROC\_WRITEPROC\_WRITEPROC\_WRITEPROC\_WRITEPROC\_WRITEPROC\_WRITEPROC\_WRITE *proc.wfd* is connected to *commands*'s standard input. The return value is a pointer to a structure with the following members: - $1$2pid\_t *pid*pid\_t *pid*pid\_t *pid*pid\_t *pid*pid\_t *pid*pid\_t *pid*pid\_t *pid*pid\_t *pid* The child process id. - $1$2pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp*pid\_t *pgrp* The child process group. - $1$2int *rfd*int *rfd*int *rfd*int *rfd*int *rfd*int *rfd*int *rfd*int *rfd* A read file descriptor connected to *command*'s standard output. - $1$2int *wfd*int *wfd*int *wfd*int *wfd*int *wfd*int *wfd*int *wfd*int *wfd* A write file descriptor connected to *command*'s standard input. If an error occurs then $1$200000000 is returned. $1$2proccloseproccloseproccloseproccloseproccloseproccloseproccloseprocclose waits for the process *proc* to complete and then closes the command stream *proc*. The command exit status is returned. $1$2-1-1-1-1-1-1-1-1 is returned if the child portion of $1$2procopenprocopenprocopenprocopenprocopenprocopenprocopenprocopen failed. $1$2procfreeprocfreeprocfreeprocfreeprocfreeprocfreeprocfreeprocfree frees the process stream without waiting for *command* to complete. Presumably some other mechanism will be used to wait for *proc.pid*. $1$2procrunprocrunprocrunprocrunprocrunprocrunprocrunprocrun combines $1$2procopenprocopenprocopenprocopenprocopenprocopenprocopenprocopen and $1$2proccloseproccloseproccloseproccloseproccloseproccloseproccloseprocclose with the flags $1$2PROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UIDPROC\_GID\|PROC\_UID and returns the command exit status. ## SEE ALSO [popen(3)](/popen/3.md), sfpopen(3), [spawnveg(3)](/spawnveg/3.md), [system(3)](/system/3.md)