usr/src/lib/libast/common/man/proc.3

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