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