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