proc(3)

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).

       procopen 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 PATH environment variable from the
       calling environment.  If command is 0 then the current  shell  is  used
       (see  pathshell(3)).  If envv is not 0 then it is a 0 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 _ environment variable is
       set to contain the pathname for command and will appear at the  top  of
       the child environment.

       If  opv is not 0 then it is a 0 terminaled vector of operations to per-
       form.  In the following context is a combination of  PROC_FD_CHILD  and
       PROC_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 SIG_DFL in the child con-
              text.

       PROC_SIG_IGN(sig)
              The signal handler for sig is set to SIG_IGN in the  child  con-
              text.

       PROC_SYS_PGRP(pgid)
              The  child process group is set to pgid.  pgid may have the fol-
              lowing values:

       <0     The child process becomes a session leader.

       0      The child process is in the parent process group.

       1      The child process becomes a process group leader.

       >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:

       PROC_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.

       PROC_BACKGROUND
              Standard shell & setup is done for the child process.

       PROC_CLEANUP
              Parent process redirection file discriptors are closed on error.

       PROC_DAEMON
              Standard daemon setup is done for the child process.

       PROC_ENVCLEAR
              The child environment is cleared before envv is added.

       PROC_GID
              The child effective group id is set to the real group id.

       PROC_IGNORE
              Parent pipe errors are ignored.

       PROC_OVERLAY
              The  current  process is overlayed by command if possible (i.e.,
              the fork(2) call is omitted).

       PROC_PARANOID
              Paranoid: command is searched using the default  standard  PATH;
              the  child environment variable PATH is set to the default stan-
              dard; the PROC_GID and PROC_UID modes are set; only  /bin/sh  is
              used to execute command if it is a shell script.

       PROC_PRIVELEGED
              If the effective user id is 0 then the child real user id is set
              to 0 and the child real group id is set to the  effective  group
              id.

       PROC_READ
              proc.rfd is connected to command's standard output.

       PROC_SESSION
              The  child  process becomes a session group leader.  (Equivalent
              to the opv entry PROC_SYS_PGRP(-1).)

       PROC_UID
              The child effective user id is set to the real user id.

       PROC_WRITE
              proc.wfd is connected to commands's standard input.

       The return value is a pointer to a structure with  the  following  mem-
       bers:

       pid_t pid
              The child process id.

       pid_t pgrp
              The child process group.

       int rfd
              A read file descriptor connected to command's standard output.

       int wfd
              A write file descriptor connected to command's standard input.

       If an error occurs then 0 is returned.

       procclose  waits  for  the process proc to complete and then closes the
       command stream proc.  The command  exit  status  is  returned.   -1  is
       returned if the child portion of procopen failed.

       procfree  frees  the process stream without waiting for command to com-
       plete.  Presumably some other  mechanism  will  be  used  to  wait  for
       proc.pid.

       procrun    combines    procopen    and   procclose   with   the   flags
       PROC_GID|PROC_UID and returns the command exit status.

SEE ALSO

       popen(3), sfpopen(3), spawnveg(3), system(3)

                                                                       PROC(3)