path: root/usr/src/lib/libast/common/man/proc.3

.fp 5 CW
.de Af
.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
..
.de aF
.ie \\$3 .ft \\$1
.el \{\
.ds ;G \&
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
.ft \\n(;G \}
..
.de L
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LR
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de RL
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de EX		\" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS 
.PD 0
.ft 5
.nf
..
.de EE		\" end example
.fi
.ft
.PD
.RE
.PP
..
.TH PROC 3
.SH NAME
proc \- process control routines
.SH SYNOPSIS
.EX
#include <proc.h>

Proc_t* procopen(const char* \fIcommand\fP, char** \fIargv\fP, char** \fIenvv\fP, long* \fIopv\fP, long \fIflags\fP);
int procfree(Proc_t* \fIproc\fP);
int procclose(Proc_t* \fIproc\fP);
int procrun(const char* \fIcommand\fP, char** \fIargv\fP);
.EE
.SH DESCRIPTION
These routines provide a portable interface to process creation and execution.
They work on systems with
.IR fork (2)
and
.IR exec (2)
as well as on systems with only
.IR spawnve (2)
or
.IR spanwveg (3).
.PP
.L procopen
runs
.I command
with arguments
.IR argv ,
environment modifications in
.IR envv ,
file descriptor, signal and process group operations in
.I opv
and flags in
.IR flags .
.PP
.I command
is searched for using the 
.L PATH
environment variable from the calling environment.
If
.I command
is 
.L 0
then the current shell is used (see
.IR pathshell (3)).
If
.I envv
is not
.L 0
then it is a 
.L 0
terminated vector of
\fIname\fP[=\fIvalue\fP]
strings that are added to the
.I command
environment using
.IR setenviron (3).
If
.I name
appears in the parent environment then its value is replaced with the new
.IR value .
If
.RI = value
is omitted then
.I name
is removed from the child environment.
The
.L _
environment variable is set to contain the pathname for
.I command
and will appear at the top of the child environment.
.PP
If
.I opv
is not 
.L 0
then it is a 0 terminaled vector of operations to perform.
In the following
.I 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:
.TP
\f5PROC_FD_CLOSE(\fIfd\fP,\fIcontext\fP)\fR
The file descriptor
.I fd
is closed in
.IR context .
.TP
\f5PROC_FD_DUP(\fIfrom\fP,\fIto\fP,\fIcontext\fP)\fR
The file descriptor
.I from
is 
.IR dup (2)'d
into the file descriptor
.I to
in
.IR context .
.TP
\f5PROC_SIG_DFL(\fIsig\fP)\fR
The signal handler for
.I sig
is set to
.L SIG_DFL
in the child context.
.TP
\f5PROC_SIG_IGN(\fIsig\fP)\fR
The signal handler for
.I sig
is set to
.L SIG_IGN
in the child context.
.TP
\f5PROC_SYS_PGRP(\fIpgid\fP)\fR
The child process group is set to
.IR pgid .
.I pgid 
may have the following values:
.TP
.L <0
The child process becomes a session leader.
.TP
.L 0
The child process is in the parent process group.
.TP
.L 1
The child process becomes a process group leader.
.TP
.L >1
The child process joins the process group
.IR pgid .
.TP
\f5PROC_SYS_UMASK(\fImask\fP)\fR
The child process group file creation mask is set to
.IR mask .
.PP
.I flags
is the inclusive-or of the following:
.TP
.L PROC_ARGMOD
.I "argv[-1]"
and
.I "argv[0]"
may be modified.
This is an optimization that avoids an environment vector
.I realloc(3)
when
.I command
is a shell script.
.TP
.L PROC_BACKGROUND
Standard shell 
.L &
setup is done for the child process.
.TP
.L PROC_CLEANUP
Parent process redirection file discriptors are closed on error.
.TP
.L PROC_DAEMON
Standard daemon setup is done for the child process.
.TP
.L PROC_ENVCLEAR
The child environment is cleared before
.I envv
is added.
.TP
.L PROC_GID
The child effective group id is set to the real group id.
.TP
.L PROC_IGNORE
Parent pipe errors are ignored.
.TP
.L PROC_OVERLAY
The current process is overlayed by
.I command
if possible
(i.e., the
.IR fork (2)
call is omitted).
.TP
.L PROC_PARANOID
Paranoid:
.I 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
.I command
if it is a shell script.
.TP
.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.
.TP
.L PROC_READ
.I proc.rfd
is connected to
.IR command 's
standard output.
.TP
.L PROC_SESSION
The child process becomes a session group leader.
(Equivalent to the
.I opv
entry
.LR PROC_SYS_PGRP(-1) .)
.TP
.L PROC_UID
The child effective user id is set to the real user id.
.TP
.L PROC_WRITE
.I proc.wfd
is connected to
.IR commands 's
standard input.
.PP
The return value is a pointer to a structure with the following members:
.TP
.L "pid_t \fIpid\fP"
The child process id.
.TP
.L "pid_t \fIpgrp\fP"
The child process group.
.TP 
.L "int \fIrfd\fP"
A read file descriptor connected to
.IR command 's
standard output.
.TP
.L "int \fIwfd\fP"
A write file descriptor connected to
.IR command 's
standard input.
.PP
If an error occurs then
.L 0
is returned.
.PP
.L procclose
waits for the process
.I proc
to complete and then closes the command stream
.IR proc .
The command exit status is returned.
.L -1
is returned if the child portion of
.L procopen
failed.
.PP
.L procfree
frees the process stream without waiting for
.I command
to complete.
Presumably some other mechanism will be used to wait for
.IR proc.pid .
.PP
.L procrun
combines 
.L procopen
and 
.L procclose
with the flags
.L PROC_GID|PROC_UID
and returns the command exit status.
.SH "SEE ALSO"
popen(3), sfpopen(3), spawnveg(3), system(3)