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