common/man/proc.3

        .fp 5 CW
..
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
..
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..


 0
..


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

If
 opv is not
.L 0
then it is a 0 terminaled vector of operations to perform.
In the following
 context is a combination of
.L PROC_FD_CHILD
and
.L PROC_FD_PARENT
for the child and parent process context respectively.
Valid operations are:

\f5PROC_FD_CLOSE(fd,context)
The file descriptor
 fd is closed in
 context .
\f5PROC_FD_DUP(from,to,context)
The file descriptor
 from is
 dup (2)'d into the file descriptor
 to in
 context .
\f5PROC_SIG_DFL(sig)
The signal handler for
 sig is set to
.L SIG_DFL
in the child context.

\f5PROC_SIG_IGN(sig)
The signal handler for
 sig is set to
.L SIG_IGN
in the child context.

\f5PROC_SYS_PGRP(pgid)
The child process group is set to
 pgid .  pgid  may have the following values:

.L <0
The child process becomes a session leader.

.L 0
The child process is in the parent process group.

.L 1
The child process becomes a process group leader.

.L >1
The child process joins the process group
 pgid .
\f5PROC_SYS_UMASK(mask)
The child process group file creation mask is set to
 mask .
 flags is the inclusive-or of the following:

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

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

.L PROC_CLEANUP
Parent process redirection file discriptors are closed on error.

.L PROC_DAEMON
Standard daemon setup is done for the child process.

.L PROC_ENVCLEAR
The child environment is cleared before
 envv is added.

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

.L PROC_IGNORE
Parent pipe errors are ignored.

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

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

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

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

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

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

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

The return value is a pointer to a structure with the following members:

.L "pid_t pid"
The child process id.

.L "pid_t pgrp"
The child process group.

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

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

If an error occurs then
.L 0
is returned.

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

.L procfree
frees the process stream without waiting for
 command to complete.
Presumably some other mechanism will be used to wait for
 proc.pid .
.L procrun
combines
.L procopen
and
.L procclose
with the flags
.L PROC_GID|PROC_UID
and returns the command exit status.
 "SEE ALSO"
popen(3), sfpopen(3), spawnveg(3), system(3)