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
 304 .Fn vfork ,
 305 thus the fork handlers are not run when
 306 .Fn posix_spawn
 307 or
 308 .Fn posix_spawnp
 309 is called.
 310 .Sh RETURN VALUES
 311 Upon successful completion,
 312 .Fn posix_spawn
 313 and
 314 .Fn posix_spawnp
 315 return the process ID of the child process to the parent process,
 316 in the variable pointed to by a non-NULL
 317 .Fa pid
 318 argument, and return zero as the function return value.
 319 Otherwise, no child process is created, no value is stored into
 320 the variable pointed to by
 321 .Fa pid ,
 322 and an error number is returned as the function return value to
 323 indicate the error.
 324 If the
 325 .Fa pid
 326 argument is a null pointer, the process ID of the child is not returned
 327 to the caller.
 328 .Sh ERRORS
 329 .Bl -enum
 330 .It
 331 If
 332 .Fn posix_spawn
 333 and
 334 .Fn posix_spawnp
 335 fail for any of the reasons that would cause
 336 .Fn vfork
 337 or one of the
 338 .Nm exec
 339 to fail, an error value is returned as described by
 340 .Fn vfork
 341 and
 342 .Nm exec ,
 343 respectively (or, if the error occurs after the calling process successfully
 344 returns, the child process exits with exit status 127).
 345 .It
 346 If
 347 .Nm POSIX_SPAWN_SETPGROUP
 348 is set in the spawn-flags attribute of the object referenced by attrp, and
 349 .Fn posix_spawn
 350 or
 351 .Fn posix_spawnp
 352 fails while changing the child's process group, an error value is returned as
 353 described by
 354 .Fn setpgid
 355 (or, if the error occurs after the calling process successfully returns,
 356 the child process exits with exit status 127).
 357 .It
 358 If
 359 .Nm POSIX_SPAWN_SETSCHEDPARAM
 360 is set and
 361 .Nm POSIX_SPAWN_SETSCHEDULER
 362 is not set in the spawn-flags attribute of the object referenced by attrp, then
 363 if
 364 .Fn posix_spawn
 365 or
 366 .Fn posix_spawnp
 367 fails for any of the reasons that would cause
 368 .Fn sched_setparam
 369 to fail, an error value is returned as described by
 370 .Fn sched_setparam
 371 (or, if the error occurs after the calling process successfully returns, the
 372 child process exits with exit status 127).
 373 .It
 374 If
 375 .Nm POSIX_SPAWN_SETSCHEDULER
 376 is set in the spawn-flags attribute of the object referenced by attrp, and if
 377 .Fn posix_spawn
 378 or
 379 .Fn posix_spawnp
 380 fails for any of the reasons that would cause
 381 .Fn sched_setscheduler
 382 to fail, an error value is returned as described by
 383 .Fn sched_setscheduler
 384 (or, if the error occurs after the calling process successfully returns,
 385 the child process exits with exit status 127).
 386 .It
 387 If the
 388 .Fa file_actions
 389 argument is not NULL, and specifies any close, dup2, or open actions to be
 390 performed, and if
 391 .Fn posix_spawn
 392 or
 393 .Fn posix_spawnp
 394 fails for any of the reasons that would cause
 395 .Fn close ,
 396 .Fn dup2 ,
 397 or
 398 .Fn open
 399 to fail, an error value is returned as described by
 400 .Fn close ,
 401 .Fn dup2 ,
 402 and
 403 .Fn open ,
 404 respectively (or, if the error occurs after the calling process successfully
 405 returns, the child process exits with exit status 127). An open file action
 406 may, by itself, result in any of the errors described by
 407 .Fn close
 408 or
 409 .Fn dup2 ,
 410 in addition to those described by
 411 .Fn open .
 412 .El
 413 .Sh SEE ALSO
 414 .Xr close 2 ,
 415 .Xr dup2 2 ,
 416 .Xr execve 2 ,
 417 .Xr fcntl 2 ,
 418 .Xr open 2 ,
 419 .Xr sched_setparam 2 ,
 420 .Xr sched_setscheduler 2 ,
 421 .Xr setpgid 2 ,
 422 .Xr vfork 2 ,
 423 .Xr posix_spawn_file_actions_addclose 3 ,
 424 .Xr posix_spawn_file_actions_adddup2 3 ,
 425 .Xr posix_spawn_file_actions_addopen 3 ,
 426 .Xr posix_spawn_file_actions_destroy 3 ,
 427 .Xr posix_spawn_file_actions_init 3 ,
 428 .Xr posix_spawnattr_destroy 3 ,
 429 .Xr posix_spawnattr_getflags 3 ,
 430 .Xr posix_spawnattr_getpgroup 3 ,
 431 .Xr posix_spawnattr_getschedparam 3 ,
 432 .Xr posix_spawnattr_getschedpolicy 3 ,
 433 .Xr posix_spawnattr_getsigdefault 3 ,
 434 .Xr posix_spawnattr_getsigmask 3 ,
 435 .Xr posix_spawnattr_init 3 ,
 436 .Xr posix_spawnattr_setflags 3 ,
 437 .Xr posix_spawnattr_setpgroup 3 ,
 438 .Xr posix_spawnattr_setschedparam 3 ,
 439 .Xr posix_spawnattr_setschedpolicy 3 ,
 440 .Xr posix_spawnattr_setsigdefault 3 ,
 441 .Xr posix_spawnattr_setsigmask 3
 442 .Sh STANDARDS
 443 The
 444 .Fn posix_spawn
 445 and
 446 .Fn posix_spawnp
 447 functions conform to
 448 .St -p1003.1-2001 .
 449 .Sh HISTORY
 450 The
 451 .Fn posix_spawn
 452 and
 453 .Fn posix_spawnp
 454 functions first appeared in
 455 .Fx 8.0 .
 456 .Sh AUTHORS
 457 .An Ed Schouten Aq Mt ed@FreeBSD.org