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 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 300If the value of the 301.Fa attrp 302pointer is NULL, then the default values are used. 303.Pp 304All process attributes, other than those influenced by the attributes 305set in the object referenced by 306.Fa attrp 307as specified above or by the file descriptor manipulations specified in 308.Fa file_actions , 309appear in the new process image as though 310.Fn vfork 311had been called to create a child process and then 312.Fn execve 313had been called by the child process to execute the new process image. 314.Pp 315The implementation uses 316.Fn vfork , 317thus the fork handlers are not run when 318.Fn posix_spawn 319or 320.Fn posix_spawnp 321is called. 322.Sh RETURN VALUES 323Upon successful completion, 324.Fn posix_spawn 325and 326.Fn posix_spawnp 327return the process ID of the child process to the parent process, 328in the variable pointed to by a non-NULL 329.Fa pid 330argument, and return zero as the function return value. 331Otherwise, no child process is created, no value is stored into 332the variable pointed to by 333.Fa pid , 334and an error number is returned as the function return value to 335indicate the error. 336If the 337.Fa pid 338argument is a null pointer, the process ID of the child is not returned 339to the caller. 340.Sh ERRORS 341.Bl -enum 342.It 343If 344.Fn posix_spawn 345and 346.Fn posix_spawnp 347fail for any of the reasons that would cause 348.Fn vfork 349or one of the 350.Nm exec 351to fail, an error value is returned as described by 352.Fn vfork 353and 354.Nm exec , 355respectively (or, if the error occurs after the calling process successfully 356returns, the child process exits with exit status 127). 357.It 358If 359.Nm POSIX_SPAWN_SETPGROUP 360is set in the spawn-flags attribute of the object referenced by attrp, and 361.Fn posix_spawn 362or 363.Fn posix_spawnp 364fails while changing the child's process group, an error value is returned as 365described by 366.Fn setpgid 367(or, if the error occurs after the calling process successfully returns, 368the child process exits with exit status 127). 369.It 370If 371.Nm POSIX_SPAWN_SETSCHEDPARAM 372is set and 373.Nm POSIX_SPAWN_SETSCHEDULER 374is not set in the spawn-flags attribute of the object referenced by attrp, then 375if 376.Fn posix_spawn 377or 378.Fn posix_spawnp 379fails for any of the reasons that would cause 380.Fn sched_setparam 381to 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 384child process exits with exit status 127). 385.It 386If 387.Nm POSIX_SPAWN_SETSCHEDULER 388is set in the spawn-flags attribute of the object referenced by attrp, and if 389.Fn posix_spawn 390or 391.Fn posix_spawnp 392fails for any of the reasons that would cause 393.Fn sched_setscheduler 394to 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, 397the child process exits with exit status 127). 398.It 399If the 400.Fa file_actions 401argument is not NULL, and specifies any dup2 or open actions to be 402performed, and if 403.Fn posix_spawn 404or 405.Fn posix_spawnp 406fails for any of the reasons that would cause 407.Fn dup2 408or 409.Fn open 410to fail, an error value is returned as described by 411.Fn dup2 412and 413.Fn open , 414respectively (or, if the error occurs after the calling process successfully 415returns, the child process exits with exit status 127). An open file action 416may, by itself, result in any of the errors described by 417.Fn dup2 , 418in addition to those described by 419.Fn open . 420This implementation ignores any errors from 421.Fn close , 422including trying to close a descriptor that is not open. 423The ignore extends to any errors from individual file descriptors 424.Fn close 425executed as part of the 426.Fn closefrom 427action. 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 462The 463.Fn posix_spawn 464and 465.Fn posix_spawnp 466functions conform to 467.St -p1003.1-2001 , 468except that they ignore all errors from 469.Fn close . 470A future update of the Standard is expected to require that these functions 471not fail because a file descriptor to be closed (via 472.Fn posix_spawn_file_actions_addclose ) 473is not open. 474.Sh HISTORY 475The 476.Fn posix_spawn 477and 478.Fn posix_spawnp 479functions first appeared in 480.Fx 8.0 . 481.Sh AUTHORS 482.An \&Ed Schouten Aq Mt ed@FreeBSD.org 483