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