1.fp 5 CW
2.de Af
3.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
4.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
5..
6.de aF
7.ie \\$3 .ft \\$1
8.el \{\
9.ds ;G \&
10.nr ;G \\n(.f
11.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12\\*(;G
13.ft \\n(;G \}
14..
15.de L
16.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17..
18.de LR
19.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20..
21.de RL
22.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23..
24.de EX		\" start example
25.ta 1i 2i 3i 4i 5i 6i
26.PP
27.RS 
28.PD 0
29.ft 5
30.nf
31..
32.de EE		\" end example
33.fi
34.ft
35.PD
36.RE
37.PP
38..
39.TH PROC 3
40.SH NAME
41proc \- process control routines
42.SH SYNOPSIS
43.EX
44#include <proc.h>
45
46Proc_t* procopen(const char* \fIcommand\fP, char** \fIargv\fP, char** \fIenvv\fP, long* \fIopv\fP, long \fIflags\fP);
47int procfree(Proc_t* \fIproc\fP);
48int procclose(Proc_t* \fIproc\fP);
49int procrun(const char* \fIcommand\fP, char** \fIargv\fP);
50.EE
51.SH DESCRIPTION
52These routines provide a portable interface to process creation and execution.
53They work on systems with
54.IR fork (2)
55and
56.IR exec (2)
57as well as on systems with only
58.IR spawnve (2)
59or
60.IR spanwveg (3).
61.PP
62.L procopen
63runs
64.I command
65with arguments
66.IR argv ,
67environment modifications in
68.IR envv ,
69file descriptor, signal and process group operations in
70.I opv
71and flags in
72.IR flags .
73.PP
74.I command
75is searched for using the 
76.L PATH
77environment variable from the calling environment.
78If
79.I command
80is 
81.L 0
82then the current shell is used (see
83.IR pathshell (3)).
84If
85.I envv
86is not
87.L 0
88then it is a 
89.L 0
90terminated vector of
91\fIname\fP[=\fIvalue\fP]
92strings that are added to the
93.I command
94environment using
95.IR setenviron (3).
96If
97.I name
98appears in the parent environment then its value is replaced with the new
99.IR value .
100If
101.RI = value
102is omitted then
103.I name
104is removed from the child environment.
105The
106.L _
107environment variable is set to contain the pathname for
108.I command
109and will appear at the top of the child environment.
110.PP
111If
112.I opv
113is not 
114.L 0
115then it is a 0 terminaled vector of operations to perform.
116In the following
117.I context
118is a combination of
119.L PROC_FD_CHILD
120and
121.L PROC_FD_PARENT
122for the child and parent process context respectively.
123Valid operations are:
124.TP
125\f5PROC_FD_CLOSE(\fIfd\fP,\fIcontext\fP)\fR
126The file descriptor
127.I fd
128is closed in
129.IR context .
130.TP
131\f5PROC_FD_DUP(\fIfrom\fP,\fIto\fP,\fIcontext\fP)\fR
132The file descriptor
133.I from
134is 
135.IR dup (2)'d
136into the file descriptor
137.I to
138in
139.IR context .
140.TP
141\f5PROC_SIG_DFL(\fIsig\fP)\fR
142The signal handler for
143.I sig
144is set to
145.L SIG_DFL
146in the child context.
147.TP
148\f5PROC_SIG_IGN(\fIsig\fP)\fR
149The signal handler for
150.I sig
151is set to
152.L SIG_IGN
153in the child context.
154.TP
155\f5PROC_SYS_PGRP(\fIpgid\fP)\fR
156The child process group is set to
157.IR pgid .
158.I pgid 
159may have the following values:
160.TP
161.L <0
162The child process becomes a session leader.
163.TP
164.L 0
165The child process is in the parent process group.
166.TP
167.L 1
168The child process becomes a process group leader.
169.TP
170.L >1
171The child process joins the process group
172.IR pgid .
173.TP
174\f5PROC_SYS_UMASK(\fImask\fP)\fR
175The child process group file creation mask is set to
176.IR mask .
177.PP
178.I flags
179is the inclusive-or of the following:
180.TP
181.L PROC_ARGMOD
182.I "argv[-1]"
183and
184.I "argv[0]"
185may be modified.
186This is an optimization that avoids an environment vector
187.I realloc(3)
188when
189.I command
190is a shell script.
191.TP
192.L PROC_BACKGROUND
193Standard shell 
194.L &
195setup is done for the child process.
196.TP
197.L PROC_CLEANUP
198Parent process redirection file discriptors are closed on error.
199.TP
200.L PROC_DAEMON
201Standard daemon setup is done for the child process.
202.TP
203.L PROC_ENVCLEAR
204The child environment is cleared before
205.I envv
206is added.
207.TP
208.L PROC_GID
209The child effective group id is set to the real group id.
210.TP
211.L PROC_IGNORE
212Parent pipe errors are ignored.
213.TP
214.L PROC_OVERLAY
215The current process is overlayed by
216.I command
217if possible
218(i.e., the
219.IR fork (2)
220call is omitted).
221.TP
222.L PROC_PARANOID
223Paranoid:
224.I command
225is searched using the default standard
226.LR PATH ;
227the child environment variable
228.L PATH
229is set to the default standard;
230the
231.L PROC_GID
232and
233.L PROC_UID
234modes are set;
235only
236.L /bin/sh
237is used to execute
238.I command
239if it is a shell script.
240.TP
241.L PROC_PRIVELEGED
242If the effective user id is
243.L 0
244then the child real user id is set to 
245.L 0
246and the child real group id is set to the effective group id.
247.TP
248.L PROC_READ
249.I proc.rfd
250is connected to
251.IR command 's
252standard output.
253.TP
254.L PROC_SESSION
255The child process becomes a session group leader.
256(Equivalent to the
257.I opv
258entry
259.LR PROC_SYS_PGRP(-1) .)
260.TP
261.L PROC_UID
262The child effective user id is set to the real user id.
263.TP
264.L PROC_WRITE
265.I proc.wfd
266is connected to
267.IR commands 's
268standard input.
269.PP
270The return value is a pointer to a structure with the following members:
271.TP
272.L "pid_t \fIpid\fP"
273The child process id.
274.TP
275.L "pid_t \fIpgrp\fP"
276The child process group.
277.TP 
278.L "int \fIrfd\fP"
279A read file descriptor connected to
280.IR command 's
281standard output.
282.TP
283.L "int \fIwfd\fP"
284A write file descriptor connected to
285.IR command 's
286standard input.
287.PP
288If an error occurs then
289.L 0
290is returned.
291.PP
292.L procclose
293waits for the process
294.I proc
295to complete and then closes the command stream
296.IR proc .
297The command exit status is returned.
298.L -1
299is returned if the child portion of
300.L procopen
301failed.
302.PP
303.L procfree
304frees the process stream without waiting for
305.I command
306to complete.
307Presumably some other mechanism will be used to wait for
308.IR proc.pid .
309.PP
310.L procrun
311combines 
312.L procopen
313and 
314.L procclose
315with the flags
316.L PROC_GID|PROC_UID
317and returns the command exit status.
318.SH "SEE ALSO"
319popen(3), sfpopen(3), spawnveg(3), system(3)
320