Imported Upstream version 93u+upstream

1 files changed, 319 insertions, 0 deletions

diff --git a/src/lib/libast/man/proc.3 b/src/lib/libast/man/proc.3
new file mode 100644
index 0000000..64c1a6e
--- /dev/null
+++ b/src/lib/libast/man/proc.3
@@ -0,0 +1,319 @@
+.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)