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 .Dd November 28, 2021
  36 .Dt POSIX_SPAWN 3
  37 .Os
  38 .Sh NAME
  39 .Nm posix_spawn ,
  40 .Nm posix_spawnp
  41 .Nd "spawn a process"
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In spawn.h
  46 .Ft int
  47 .Fo posix_spawn
  48 .Fa "pid_t *restrict pid"
  49 .Fa "const char *restrict path"
  50 .Fa "const posix_spawn_file_actions_t *file_actions"
  51 .Fa "const posix_spawnattr_t *restrict attrp"
  52 .Fa "char *const argv[restrict]"
  53 .Fa "char *const envp[restrict]"
  54 .Fc
  55 .Ft int
  56 .Fo posix_spawnp
  57 .Fa "pid_t *restrict pid"
  58 .Fa "const char *restrict file"
  59 .Fa "const posix_spawn_file_actions_t *file_actions"
  60 .Fa "const posix_spawnattr_t *restrict attrp"
  61 .Fa "char *const argv[restrict]"
  62 .Fa "char *const envp[restrict]"
  63 .Fc
  64 .Sh DESCRIPTION
  65 The
  66 .Fn posix_spawn
  67 and
  68 .Fn posix_spawnp
  69 functions create a new process (child process) from the specified
  70 process image.
  71 The new process image is constructed from a regular executable
  72 file called the new process image file.
  73 .Pp
  74 When a C program is executed as the result of this call, it is
  75 entered as a C-language function call as follows:
  76 .Bd -literal -offset indent
  77 int main(int argc, char *argv[]);
  78 .Ed
  79 .Pp
  80 where
  81 .Fa argc
  82 is the argument count and
  83 .Fa argv
  84 is an array of character pointers to the arguments themselves.
  85 In addition, the variable:
  86 .Bd -literal -offset indent
  87 extern char **environ;
  88 .Ed
  89 .Pp
  90 points to an array of character pointers to
  91 the environment strings.
  92 .Pp
  93 The argument
  94 .Fa argv
  95 is an array of character pointers to null-terminated
  96 strings.
  97 The last member of this array is a null pointer and is not counted
  98 in
  99 .Fa argc .
 100 These strings constitute the argument list available to the new process
 101 image.
 102 The value in
 103 .Fa argv Ns [0]
 104 should point to
 105 a filename that is associated with the process image being started by
 106 the
 107 .Fn posix_spawn
 108 or
 109 .Fn posix_spawnp
 110 function.
 111 .Pp
 112 The argument
 113 .Fa envp
 114 is an array of character pointers to null-terminated strings.
 115 These strings constitute the environment for the new process image.
 116 The environment array is terminated by a null pointer.
 117 .Pp
 118 The
 119 .Fa path
 120 argument to
 121 .Fn posix_spawn
 122 is a pathname that identifies the new process image file to execute.
 123 .Pp
 124 The
 125 .Fa file
 126 parameter to
 127 .Fn posix_spawnp
 128 is used to construct a pathname that identifies the new process
 129 image file.
 130 If the file parameter contains a slash character, the file parameter
 131 is used as the pathname for the new process image file.
 132 Otherwise, the path prefix for this file is obtained by a search
 133 of the directories passed as the environment variable
 134 .Dq Ev PATH .
 135 If this variable is not specified,
 136 the default path is set according to the
 137 .Dv _PATH_DEFPATH
 138 definition in
 139 .In paths.h ,
 140 which is set to
 141 .Dq Ev /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
 142 .Pp
 143 If
 144 .Fa file_actions
 145 is a null pointer, then file descriptors open in the
 146 calling process remain open in the child process, except for those
 147 whose close-on-exec flag
 148 .Dv FD_CLOEXEC
 149 is set (see
 150 .Fn fcntl ) .
 151 For those
 152 file descriptors that remain open, all attributes of the corresponding
 153 open file descriptions, including file locks (see
 154 .Fn fcntl ) ,
 155 remain unchanged.
 156 .Pp
 157 If
 158 .Fa file_actions
 159 is not NULL, then the file descriptors open in the child process are
 160 those open in the calling process as modified by the spawn file
 161 actions object pointed to by
 162 .Fa file_actions
 163 and the
 164 .Dv FD_CLOEXEC
 165 flag of each remaining open file descriptor after the spawn file actions
 166 have been processed.
 167 The effective order of processing the spawn file actions are:
 168 .Bl -enum
 169 .It
 170 The set of open file descriptors for the child process initially
 171 are the same set as is open for the calling process.
 172 All attributes of the corresponding open file descriptions, including
 173 file locks (see
 174 .Fn fcntl ) ,
 175 remain unchanged.
 176 .It
 177 The signal mask, signal default actions, and the effective user and
 178 group IDs for the child process are changed as specified in the
 179 attributes object referenced by
 180 .Fa attrp .
 181 .It
 182 The file actions specified by the spawn file actions object are
 183 performed in the order in which they were added to the spawn file
 184 actions object.
 185 .It
 186 Any file descriptor that has its
 187 .Dv FD_CLOEXEC
 188 flag set (see
 189 .Fn fcntl )
 190 is closed.
 191 .El
 192 .Pp
 193 The
 194 .Vt posix_spawnattr_t
 195 spawn attributes object type is defined in
 196 .In spawn.h .
 197 It contains the attributes defined below.
 198 .Pp
 199 If the
 200 .Dv POSIX_SPAWN_SETPGROUP
 201 flag is set in the spawn-flags attribute of the object referenced by
 202 .Fa attrp ,
 203 and the spawn-pgroup attribute of the same object is non-zero, then the
 204 child's process group is as specified in the spawn-pgroup
 205 attribute of the object referenced by
 206 .Fa attrp .
 207 .Pp
 208 As a special case, if the
 209 .Dv POSIX_SPAWN_SETPGROUP
 210 flag is set in the spawn-flags attribute of the object referenced by
 211 .Fa attrp ,
 212 and the spawn-pgroup attribute of the same object is set to zero, then
 213 the child is in a new process group with a process group ID equal
 214 to its process ID.
 215 .Pp
 216 If the
 217 .Dv POSIX_SPAWN_SETPGROUP
 218 flag is not set in the spawn-flags attribute of the object referenced by
 219 .Fa attrp ,
 220 the new child process inherits the parent's process group.
 221 .Pp
 222 If the
 223 .Dv POSIX_SPAWN_SETSCHEDPARAM
 224 flag is set in the spawn-flags attribute of the object referenced by
 225 .Fa attrp ,
 226 but
 227 .Dv POSIX_SPAWN_SETSCHEDULER
 228 is not set, the new process image initially has the scheduling
 229 policy of the calling process with the scheduling parameters specified
 230 in the spawn-schedparam attribute of the object referenced by
 231 .Fa attrp .
 232 .Pp
 233 If the
 234 .Dv POSIX_SPAWN_SETSCHEDULER
 235 flag is set in the spawn-flags attribute of the object referenced by
 236 .Fa attrp
 237 (regardless of the setting of the
 238 .Dv POSIX_SPAWN_SETSCHEDPARAM
 239 flag), the new process image initially has the scheduling policy
 240 specified in the spawn-schedpolicy attribute of the object referenced by
 241 .Fa attrp
 242 and the scheduling parameters specified in the spawn-schedparam
 243 attribute of the same object.
 244 .Pp
 245 The
 246 .Dv POSIX_SPAWN_RESETIDS
 247 flag in the spawn-flags attribute of the object referenced by
 248 .Fa attrp
 249 governs the effective user ID of the child process.
 250 If this flag is not set, the child process inherits the parent
 251 process' effective user ID.
 252 If this flag is set, the child process' effective user ID is reset
 253 to the parent's real user ID.
 254 In either case, if the set-user-ID mode bit of the new process image
 255 file is set, the effective user ID of the child process becomes
 256 that file's owner ID before the new process image begins execution.
 257 .Pp
 258 The
 259 .Dv POSIX_SPAWN_RESETIDS
 260 flag in the spawn-flags attribute of the object referenced by
 261 .Fa attrp
 262 also governs the effective group ID of the child process.
 263 If this flag is not set, the child process inherits the parent
 264 process' effective group ID.
 265 If this flag is set, the child process' effective group ID is
 266 reset to the parent's real group ID.
 267 In either case, if the set-group-ID mode bit of the new process image
 268 file is set, the effective group ID of the child process becomes
 269 that file's group ID before the new process image begins execution.
 270 .Pp
 271 If the
 272 .Dv POSIX_SPAWN_SETSIGMASK
 273 flag is set in the spawn-flags attribute of the object referenced by
 274 .Fa attrp ,
 275 the child process initially has the signal mask specified in the
 276 spawn-sigmask attribute of the object referenced by
 277 .Fa attrp .
 278 .Pp
 279 If the
 280 .Dv POSIX_SPAWN_SETSIGDEF
 281 flag is set in the spawn-flags attribute of the object referenced by
 282 .Fa attrp ,
 283 the signals specified in the spawn-sigdefault attribute of the same
 284 object are set to their default actions in the child process.
 285 Signals set to the default action in the parent process are set to
 286 the default action in the child process.
 287 .Pp
 288 Signals set to be caught by the calling process are set to the
 289 default action in the child process.
 290 .Pp
 291 Signals set to be ignored by the calling process image are set to
 292 be ignored by the child process, unless otherwise specified by the
 293 .Dv POSIX_SPAWN_SETSIGDEF
 294 flag being set in the spawn-flags attribute of the object referenced by
 295 .Fa attrp
 296 and the signals being indicated in the spawn-sigdefault attribute
 297 of the object referenced by
 298 .Fa attrp .
 299 .Pp
 300 If the value of the
 301 .Fa attrp
 302 pointer is NULL, then the default values are used.
 303 .Pp
 304 All process attributes, other than those influenced by the attributes
 305 set in the object referenced by
 306 .Fa attrp
 307 as specified above or by the file descriptor manipulations specified in
 308 .Fa file_actions ,
 309 appear in the new process image as though
 310 .Fn vfork
 311 had been called to create a child process and then
 312 .Fn execve
 313 had been called by the child process to execute the new process image.
 314 .Pp
 315 The implementation uses
 316 .Fn vfork ,
 317 thus the fork handlers are not run when
 318 .Fn posix_spawn
 319 or
 320 .Fn posix_spawnp
 321 is called.
 322 .Sh RETURN VALUES
 323 Upon successful completion,
 324 .Fn posix_spawn
 325 and
 326 .Fn posix_spawnp
 327 return the process ID of the child process to the parent process,
 328 in the variable pointed to by a non-NULL
 329 .Fa pid
 330 argument, and return zero as the function return value.
 331 Otherwise, no child process is created, no value is stored into
 332 the variable pointed to by
 333 .Fa pid ,
 334 and an error number is returned as the function return value to
 335 indicate the error.
 336 If the
 337 .Fa pid
 338 argument is a null pointer, the process ID of the child is not returned
 339 to the caller.
 340 .Sh ERRORS
 341 .Bl -enum
 342 .It
 343 If
 344 .Fn posix_spawn
 345 and
 346 .Fn posix_spawnp
 347 fail for any of the reasons that would cause
 348 .Fn vfork
 349 or one of the
 350 .Nm exec
 351 to fail, an error value is returned as described by
 352 .Fn vfork
 353 and
 354 .Nm exec ,
 355 respectively (or, if the error occurs after the calling process successfully
 356 returns, the child process exits with exit status 127).
 357 .It
 358 If
 359 .Nm POSIX_SPAWN_SETPGROUP
 360 is set in the spawn-flags attribute of the object referenced by attrp, and
 361 .Fn posix_spawn
 362 or
 363 .Fn posix_spawnp
 364 fails while changing the child's process group, an error value is returned as
 365 described by
 366 .Fn setpgid
 367 (or, if the error occurs after the calling process successfully returns,
 368 the child process exits with exit status 127).
 369 .It
 370 If
 371 .Nm POSIX_SPAWN_SETSCHEDPARAM
 372 is set and
 373 .Nm POSIX_SPAWN_SETSCHEDULER
 374 is not set in the spawn-flags attribute of the object referenced by attrp, then
 375 if
 376 .Fn posix_spawn
 377 or
 378 .Fn posix_spawnp
 379 fails for any of the reasons that would cause
 380 .Fn sched_setparam
 381 to fail, an error value is returned as described by
 382 .Fn sched_setparam
 383 (or, if the error occurs after the calling process successfully returns, the
 384 child process exits with exit status 127).
 385 .It
 386 If
 387 .Nm POSIX_SPAWN_SETSCHEDULER
 388 is set in the spawn-flags attribute of the object referenced by attrp, and if
 389 .Fn posix_spawn
 390 or
 391 .Fn posix_spawnp
 392 fails for any of the reasons that would cause
 393 .Fn sched_setscheduler
 394 to fail, an error value is returned as described by
 395 .Fn sched_setscheduler
 396 (or, if the error occurs after the calling process successfully returns,
 397 the child process exits with exit status 127).
 398 .It
 399 If the
 400 .Fa file_actions
 401 argument is not NULL, and specifies any dup2 or open actions to be
 402 performed, and if
 403 .Fn posix_spawn
 404 or
 405 .Fn posix_spawnp
 406 fails for any of the reasons that would cause
 407 .Fn dup2
 408 or
 409 .Fn open
 410 to fail, an error value is returned as described by
 411 .Fn dup2
 412 and
 413 .Fn open ,
 414 respectively (or, if the error occurs after the calling process successfully
 415 returns, the child process exits with exit status 127). An open file action
 416 may, by itself, result in any of the errors described by
 417 .Fn dup2 ,
 418 in addition to those described by
 419 .Fn open .
 420 This implementation ignores any errors from
 421 .Fn close ,
 422 including trying to close a descriptor that is not open.
 423 The ignore extends to any errors from individual file descriptors
 424 .Fn close
 425 executed as part of the
 426 .Fn closefrom
 427 action.
 428 .El
 429 .Sh SEE ALSO
 430 .Xr close 2 ,
 431 .Xr dup2 2 ,
 432 .Xr execve 2 ,
 433 .Xr fcntl 2 ,
 434 .Xr open 2 ,
 435 .Xr sched_setparam 2 ,
 436 .Xr sched_setscheduler 2 ,
 437 .Xr setpgid 2 ,
 438 .Xr vfork 2 ,
 439 .Xr posix_spawn_file_actions_addclose 3 ,
 440 .Xr posix_spawn_file_actions_addclosefrom_np 3 ,
 441 .Xr posix_spawn_file_actions_adddup2 3 ,
 442 .Xr posix_spawn_file_actions_addopen 3 ,
 443 .Xr posix_spawn_file_actions_addchdir_np 3 ,
 444 .Xr posix_spawn_file_actions_addfchdir_np 3 ,
 445 .Xr posix_spawn_file_actions_destroy 3 ,
 446 .Xr posix_spawn_file_actions_init 3 ,
 447 .Xr posix_spawnattr_destroy 3 ,
 448 .Xr posix_spawnattr_getflags 3 ,
 449 .Xr posix_spawnattr_getpgroup 3 ,
 450 .Xr posix_spawnattr_getschedparam 3 ,
 451 .Xr posix_spawnattr_getschedpolicy 3 ,
 452 .Xr posix_spawnattr_getsigdefault 3 ,
 453 .Xr posix_spawnattr_getsigmask 3 ,
 454 .Xr posix_spawnattr_init 3 ,
 455 .Xr posix_spawnattr_setflags 3 ,
 456 .Xr posix_spawnattr_setpgroup 3 ,
 457 .Xr posix_spawnattr_setschedparam 3 ,
 458 .Xr posix_spawnattr_setschedpolicy 3 ,
 459 .Xr posix_spawnattr_setsigdefault 3 ,
 460 .Xr posix_spawnattr_setsigmask 3
 461 .Sh STANDARDS
 462 The
 463 .Fn posix_spawn
 464 and
 465 .Fn posix_spawnp
 466 functions conform to
 467 .St -p1003.1-2001 ,
 468 except that they ignore all errors from
 469 .Fn close .
 470 A future update of the Standard is expected to require that these functions
 471 not fail because a file descriptor to be closed (via
 472 .Fn posix_spawn_file_actions_addclose )
 473 is not open.
 474 .Sh HISTORY
 475 The
 476 .Fn posix_spawn
 477 and
 478 .Fn posix_spawnp
 479 functions first appeared in
 480 .Fx 8.0 .
 481 .Sh AUTHORS
 482 .An \&Ed Schouten Aq Mt ed@FreeBSD.org