lib/libc/gen/posix_spawn.3

   1 .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" Portions of this text are reprinted and reproduced in electronic form
  26 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
  27 .\" Portable Operating System Interface (POSIX), The Open Group Base
  28 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
  29 .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
  30 .\" event of any discrepancy between this version and the original IEEE and
  31 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
  32 .\" the referee document.  The original Standard can be obtained online at
  33 .\"     http://www.opengroup.org/unix/online.html.
  34 .\"
  35 .\" $FreeBSD: src/lib/libc/gen/posix_spawn.3,v 1.2 2008/07/28 09:36:56 ed Exp $
  36 .\"
  37 .Dd April 7, 2009
  38 .Dt POSIX_SPAWN 3
  39 .Os
  40 .Sh NAME
  41 .Nm posix_spawn ,
  42 .Nm posix_spawnp
  43 .Nd "spawn a process"
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In spawn.h
  48 .Ft int
  49 .Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
  50 .Ft int
  51 .Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn posix_spawn
  55 and
  56 .Fn posix_spawnp
  57 functions create a new process (child process) from the specified
  58 process image.
  59 The new process image is constructed from a regular executable
  60 file called the new process image file.
  61 .Pp
  62 When a C program is executed as the result of this call, it is
  63 entered as a C-language function call as follows:
  64 .Bd -literal -offset indent
  65 int main(int argc, char *argv[]);
  66 .Ed
  67 .Pp
  68 where
  69 .Fa argc
  70 is the argument count and
  71 .Fa argv
  72 is an array of character pointers to the arguments themselves.
  73 In addition, the variable:
  74 .Bd -literal -offset indent
  75 extern char **environ;
  76 .Ed
  77 .Pp
  78 points to an array of character pointers to
  79 the environment strings.
  80 .Pp
  81 The argument
  82 .Fa argv
  83 is an array of character pointers to null-terminated
  84 strings.
  85 The last member of this array is a null pointer and is not counted
  86 in
  87 .Fa argc .
  88 These strings constitute the argument list available to the new process
  89 image.
  90 The value in
  91 .Fa argv Ns [0]
  92 should point to
  93 a filename that is associated with the process image being started by
  94 the
  95 .Fn posix_spawn
  96 or
  97 .Fn posix_spawnp
  98 function.
  99 .Pp
 100 The argument
 101 .Fa envp
 102 is an array of character pointers to null-terminated strings.
 103 These strings constitute the environment for the new process image.
 104 The environment array is terminated by a null pointer.
 105 .Pp
 106 The
 107 .Fa path
 108 argument to
 109 .Fn posix_spawn
 110 is a pathname that identifies the new process image file to execute.
 111 .Pp
 112 The
 113 .Fa file
 114 parameter to
 115 .Fn posix_spawnp
 116 is used to construct a pathname that identifies the new process
 117 image file.
 118 If the file parameter contains a slash character, the file parameter
 119 is used as the pathname for the new process image file.
 120 Otherwise, the path prefix for this file is obtained by a search
 121 of the directories passed as the environment variable
 122 .Dq Ev PATH .
 123 If this variable is not specified,
 124 the default path is set according to the
 125 .Dv _PATH_DEFPATH
 126 definition in
 127 .In paths.h ,
 128 which is set to
 129 .Dq Ev /usr/bin:/bin .
 130 .Pp
 131 If
 132 .Fa file_actions
 133 is a null pointer, then file descriptors open in the
 134 calling process remain open in the child process, except for those
 135 whose close-on-exec flag
 136 .Dv FD_CLOEXEC
 137 is set (see
 138 .Fn fcntl ) .
 139 For those
 140 file descriptors that remain open, all attributes of the corresponding
 141 open file descriptions, including file locks (see
 142 .Fn fcntl ) ,
 143 remain unchanged.
 144 .Pp
 145 If
 146 .Fa file_actions
 147 is not NULL, then the file descriptors open in the child process are
 148 those open in the calling process as modified by the spawn file
 149 actions object pointed to by
 150 .Fa file_actions
 151 and the
 152 .Dv FD_CLOEXEC
 153 flag of each remaining open file descriptor after the spawn file actions
 154 have been processed.
 155 The effective order of processing the spawn file actions are:
 156 .Bl -enum
 157 .It
 158 The set of open file descriptors for the child process initially
 159 are the same set as is open for the calling process.
 160 All attributes of the corresponding open file descriptions, including
 161 file locks (see
 162 .Fn fcntl ) ,
 163 remain unchanged.
 164 .It
 165 The signal mask, signal default actions, and the effective user and
 166 group IDs for the child process are changed as specified in the
 167 attributes object referenced by
 168 .Fa attrp .
 169 .It
 170 The file actions specified by the spawn file actions object are
 171 performed in the order in which they were added to the spawn file
 172 actions object.
 173 .It
 174 Any file descriptor that has its
 175 .Dv FD_CLOEXEC
 176 flag set (see
 177 .Fn fcntl )
 178 is closed.
 179 .El
 180 .Pp
 181 The
 182 .Vt posix_spawnattr_t
 183 spawn attributes object type is defined in
 184 .In spawn.h .
 185 It contains the attributes defined below.
 186 .Pp
 187 If the
 188 .Dv POSIX_SPAWN_SETPGROUP
 189 flag is set in the spawn-flags attribute of the object referenced by
 190 .Fa attrp ,
 191 and the spawn-pgroup attribute of the same object is non-zero, then the
 192 child's process group is as specified in the spawn-pgroup
 193 attribute of the object referenced by
 194 .Fa attrp .
 195 .Pp
 196 As a special case, if the
 197 .Dv POSIX_SPAWN_SETPGROUP
 198 flag is set in the spawn-flags attribute of the object referenced by
 199 .Fa attrp ,
 200 and the spawn-pgroup attribute of the same object is set to zero, then
 201 the child is in a new process group with a process group ID equal
 202 to its process ID.
 203 .Pp
 204 If the
 205 .Dv POSIX_SPAWN_SETPGROUP
 206 flag is not set in the spawn-flags attribute of the object referenced by
 207 .Fa attrp ,
 208 the new child process inherits the parent's process group.
 209 .Pp
 210 If the
 211 .Dv POSIX_SPAWN_SETSCHEDPARAM
 212 flag is set in the spawn-flags attribute of the object referenced by
 213 .Fa attrp ,
 214 but
 215 .Dv POSIX_SPAWN_SETSCHEDULER
 216 is not set, the new process image initially has the scheduling
 217 policy of the calling process with the scheduling parameters specified
 218 in the spawn-schedparam attribute of the object referenced by
 219 .Fa attrp .
 220 .Pp
 221 If the
 222 .Dv POSIX_SPAWN_SETSCHEDULER
 223 flag is set in the spawn-flags attribute of the object referenced by
 224 .Fa attrp
 225 (regardless of the setting of the
 226 .Dv POSIX_SPAWN_SETSCHEDPARAM
 227 flag), the new process image initially has the scheduling policy
 228 specified in the spawn-schedpolicy attribute of the object referenced by
 229 .Fa attrp
 230 and the scheduling parameters specified in the spawn-schedparam
 231 attribute of the same object.
 232 .Pp
 233 The
 234 .Dv POSIX_SPAWN_RESETIDS
 235 flag in the spawn-flags attribute of the object referenced by
 236 .Fa attrp
 237 governs the effective user ID of the child process.
 238 If this flag is not set, the child process inherits the parent
 239 process' effective user ID.
 240 If this flag is set, the child process' effective user ID is reset
 241 to the parent's real user ID.
 242 In either case, if the set-user-ID mode bit of the new process image
 243 file is set, the effective user ID of the child process becomes
 244 that file's owner ID before the new process image begins execution.
 245 .Pp
 246 The
 247 .Dv POSIX_SPAWN_RESETIDS
 248 flag in the spawn-flags attribute of the object referenced by
 249 .Fa attrp
 250 also governs the effective group ID of the child process.
 251 If this flag is not set, the child process inherits the parent
 252 process' effective group ID.
 253 If this flag is set, the child process' effective group ID is
 254 reset to the parent's real group ID.
 255 In either case, if the set-group-ID mode bit of the new process image
 256 file is set, the effective group ID of the child process becomes
 257 that file's group ID before the new process image begins execution.
 258 .Pp
 259 If the
 260 .Dv POSIX_SPAWN_SETSIGMASK
 261 flag is set in the spawn-flags attribute of the object referenced by
 262 .Fa attrp ,
 263 the child process initially has the signal mask specified in the
 264 spawn-sigmask attribute of the object referenced by
 265 .Fa attrp .
 266 .Pp
 267 If the
 268 .Dv POSIX_SPAWN_SETSIGDEF
 269 flag is set in the spawn-flags attribute of the object referenced by
 270 .Fa attrp ,
 271 the signals specified in the spawn-sigdefault attribute of the same
 272 object is set to their default actions in the child process.
 273 Signals set to the default action in the parent process is set to
 274 the default action in the child process.
 275 .Pp
 276 Signals set to be caught by the calling process is set to the
 277 default action in the child process.
 278 .Pp
 279 Signals set to be ignored by the calling process image is set to
 280 be ignored by the child process, unless otherwise specified by the
 281 .Dv POSIX_SPAWN_SETSIGDEF
 282 flag being set in the spawn-flags attribute of the object referenced by
 283 .Fa attrp
 284 and the signals being indicated in the spawn-sigdefault attribute
 285 of the object referenced by
 286 .Fa attrp .
 287 .Pp
 288 If the value of the
 289 .Fa attrp
 290 pointer is NULL, then the default values are used.
 291 .Pp
 292 All process attributes, other than those influenced by the attributes
 293 set in the object referenced by
 294 .Fa attrp
 295 as specified above or by the file descriptor manipulations specified in
 296 .Fa file_actions ,
 297 appear in the new process image as though
 298 .Fn vfork
 299 had been called to create a child process and then
 300 .Fn execve
 301 had been called by the child process to execute the new process image.
 302 .Pp
 303 The implementation uses vfork(), thus the fork handlers are not run when
 304 .Fn posix_spawn
 305 or
 306 .Fn posix_spawnp
 307 is called.
 308 .Sh RETURN VALUES
 309 Upon successful completion,
 310 .Fn posix_spawn
 311 and
 312 .Fn posix_spawnp
 313 return the process ID of the child process to the parent process,
 314 in the variable pointed to by a non-NULL
 315 .Fa pid
 316 argument, and return zero as the function return value.
 317 Otherwise, no child process is created, no value is stored into
 318 the variable pointed to by
 319 .Fa pid ,
 320 and an error number is returned as the function return value to
 321 indicate the error.
 322 If the
 323 .Fa pid
 324 argument is a null pointer, the process ID of the child is not returned
 325 to the caller.
 326 .Sh ERRORS
 327 .Bl -enum
 328 .It
 329 If
 330 .Fn posix_spawn
 331 and
 332 .Fn posix_spawnp
 333 fail for any of the reasons that would cause
 334 .Fn vfork
 335 or one of the
 336 .Nm exec
 337 to fail, an error value is returned as described by
 338 .Fn vfork
 339 and
 340 .Nm exec ,
 341 respectively (or, if the error occurs after the calling process successfully
 342 returns, the child process exits with exit status 127).
 343 .It
 344 If
 345 .Nm POSIX_SPAWN_SETPGROUP
 346 is set in the spawn-flags attribute of the object referenced by attrp, and
 347 .Fn posix_spawn
 348 or
 349 .Fn posix_spawnp
 350 fails while changing the child's process group, an error value is returned as
 351 described by
 352 .Fn setpgid
 353 (or, if the error occurs after the calling process successfully returns,
 354 the child process exits with exit status 127).
 355 .It
 356 If
 357 .Nm POSIX_SPAWN_SETSCHEDPARAM
 358 is set and
 359 .Nm POSIX_SPAWN_SETSCHEDULER
 360 is not set in the spawn-flags attribute of the object referenced by attrp, then
 361 if
 362 .Fn posix_spawn
 363 or
 364 .Fn posix_spawnp
 365 fails for any of the reasons that would cause
 366 .Fn sched_setparam
 367 to fail, an error value is returned as described by
 368 .Fn sched_setparam
 369 (or, if the error occurs after the calling process successfully returns, the
 370 child process exits with exit status 127).
 371 .It
 372 If
 373 .Nm POSIX_SPAWN_SETSCHEDULER
 374 is set in the spawn-flags attribute of the object referenced by attrp, and if
 375 .Fn posix_spawn
 376 or
 377 .Fn posix_spawnp
 378 fails for any of the reasons that would cause
 379 .Fn sched_setscheduler
 380 to fail, an error value is returned as described by
 381 .Fn sched_setscheduler
 382 (or, if the error occurs after the calling process successfully returns,
 383 the child process exits with exit status 127).
 384 .It
 385 If the
 386 .Fa file_actions
 387 argument is not NULL, and specifies any close, dup2, or open actions to be
 388 performed, and if
 389 .Fn posix_spawn
 390 or
 391 .Fn posix_spawnp
 392 fails for any of the reasons that would cause
 393 .Fn close ,
 394 .Fn dup2 ,
 395 or
 396 .Fn open
 397 to fail, an error value is returned as described by
 398 .Fn close ,
 399 .Fn dup2 ,
 400 and
 401 .Fn open ,
 402 respectively (or, if the error occurs after the calling process successfully
 403 returns, the child process exits with exit status 127). An open file action
 404 may, by itself, result in any of the errors described by
 405 .Fn close
 406 or
 407 .Fn dup2 ,
 408 in addition to those described by
 409 .Fn open .
 410 .El
 411 .Sh SEE ALSO
 412 .Xr close 2 ,
 413 .Xr dup2 2 ,
 414 .Xr execve 2 ,
 415 .Xr fcntl 2 ,
 416 .Xr open 2 ,
 417 .Xr sched_setparam 2 ,
 418 .Xr sched_setscheduler 2 ,
 419 .Xr setpgid 2 ,
 420 .Xr vfork 2 ,
 421 .Xr posix_spawn_file_actions_addclose 3 ,
 422 .Xr posix_spawn_file_actions_adddup2 3 ,
 423 .Xr posix_spawn_file_actions_addopen 3 ,
 424 .Xr posix_spawn_file_actions_destroy 3 ,
 425 .Xr posix_spawn_file_actions_init 3 ,
 426 .Xr posix_spawnattr_destroy 3 ,
 427 .Xr posix_spawnattr_getflags 3 ,
 428 .Xr posix_spawnattr_getpgroup 3 ,
 429 .Xr posix_spawnattr_getschedparam 3 ,
 430 .Xr posix_spawnattr_getschedpolicy 3 ,
 431 .Xr posix_spawnattr_getsigdefault 3 ,
 432 .Xr posix_spawnattr_getsigmask 3 ,
 433 .Xr posix_spawnattr_init 3 ,
 434 .Xr posix_spawnattr_setflags 3 ,
 435 .Xr posix_spawnattr_setpgroup 3 ,
 436 .Xr posix_spawnattr_setschedparam 3 ,
 437 .Xr posix_spawnattr_setschedpolicy 3 ,
 438 .Xr posix_spawnattr_setsigdefault 3 ,
 439 .Xr posix_spawnattr_setsigmask 3
 440 .Sh STANDARDS
 441 The
 442 .Fn posix_spawn
 443 and
 444 .Fn posix_spawnp
 445 functions conform to
 446 .St -p1003.1-2001 .
 447 .Sh HISTORY
 448 The
 449 .Fn posix_spawn
 450 and
 451 .Fn posix_spawnp
 452 functions first appeared in
 453 .Fx 8.0 .
 454 .Sh AUTHORS
 455 .An Ed Schouten Aq ed@FreeBSD.org