proc(3) · carta

NAME

proc - process control routines

SYNOPSIS

#include <proc.h>
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) 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). 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)'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) 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) 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 pidpid_t pidpid_t pidpid_t pidpid_t pidpid_t pidpid_t pidpid_t pid: The child process id.

$1$2pid_t pgrppid_t pgrppid_t pgrppid_t pgrppid_t pgrppid_t pgrppid_t pgrppid_t pgrp: The child process group.

$1$2int rfdint rfdint rfdint rfdint rfdint rfdint rfdint rfd: A read file descriptor connected to command's standard output.

$1$2int wfdint wfdint wfdint wfdint wfdint wfdint wfdint 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.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO