1.\" $NetBSD: posix_spawn.3,v 1.13 2021/11/15 14:06:50 wiz Exp $ 2.\" 3.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Portions of this text are reprinted and reproduced in electronic form 28.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 29.\" Portable Operating System Interface (POSIX), The Open Group Base 30.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 31.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 32.\" event of any discrepancy between this version and the original IEEE and 33.\" The Open Group Standard, the original IEEE and The Open Group Standard is 34.\" the referee document. The original Standard can be obtained online at 35.\" http://www.opengroup.org/unix/online.html. 36.\" 37.\" $FreeBSD: src/lib/libc/gen/posix_spawn.3,v 1.2.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $ 38.\" 39.Dd June 11, 2019 40.Dt POSIX_SPAWN 3 41.Os 42.Sh NAME 43.Nm posix_spawn , 44.Nm posix_spawnp 45.Nd "spawn a process" 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In spawn.h 50.Ft int 51.Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" 52.Ft int 53.Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" 54.Sh DESCRIPTION 55The 56.Fn posix_spawn 57and 58.Fn posix_spawnp 59functions create a new process (child process) from the specified 60process image. 61The new process image is constructed from a regular executable 62file called the new process image file. 63.Pp 64When a C program is executed as the result of this call, it is 65entered as a C-language function call as follows: 66.Bd -literal -offset indent 67int main(int argc, char *argv[]); 68.Ed 69.Pp 70where 71.Fa argc 72is the argument count and 73.Fa argv 74is an array of character pointers to the arguments themselves. 75In addition, the variable: 76.Bd -literal -offset indent 77extern char **environ; 78.Ed 79.Pp 80points to an array of character pointers to 81the environment strings. 82.Pp 83The argument 84.Fa argv 85is an array of character pointers to null-terminated 86strings. 87The last member of this array is a null pointer and is not counted 88in 89.Fa argc . 90These strings constitute the argument list available to the new process 91image. 92The value in 93.Fa argv Ns [0] 94should point to 95a filename that is associated with the process image being started by 96the 97.Fn posix_spawn 98or 99.Fn posix_spawnp 100function. 101.Pp 102The argument 103.Fa envp 104is an array of character pointers to null-terminated strings. 105These strings constitute the environment for the new process image. 106The environment array is terminated by a null pointer. 107.Pp 108The 109.Fa path 110argument to 111.Fn posix_spawn 112is a pathname that identifies the new process image file to execute. 113.Pp 114The 115.Fa file 116parameter to 117.Fn posix_spawnp 118is used to construct a pathname that identifies the new process 119image file. 120If the file parameter contains a slash character, the file parameter 121is used as the pathname for the new process image file. 122Otherwise, the path prefix for this file is obtained by a search 123of the directories passed as the environment variable 124.Dq Ev PATH . 125If this variable is not specified, 126the default path is set according to the 127.Dv _PATH_DEFPATH 128definition in 129.In paths.h , 130which is set to 131.Dq Ev /usr/bin:/bin . 132.Pp 133If 134.Fa file_actions 135is a null pointer, then file descriptors open in the 136calling process remain open in the child process, except for those 137whose close-on-exec flag 138.Dv FD_CLOEXEC 139is set (see 140.Fn fcntl ) . 141For those 142file descriptors that remain open, all attributes of the corresponding 143open file descriptions, including file locks (see 144.Fn fcntl ) , 145remain unchanged. 146.Pp 147If 148.Fa file_actions 149is not 150.Dv NULL , 151then the file descriptors open in the child process are 152those open in the calling process as modified by the spawn file 153actions object pointed to by 154.Fa file_actions 155and the 156.Dv FD_CLOEXEC 157flag of each remaining open file descriptor after the spawn file actions 158have been processed. 159The effective order of processing the spawn file actions are: 160.Bl -enum 161.It 162The set of open file descriptors for the child process initially 163are the same set as is open for the calling process. 164All attributes of the corresponding open file descriptions, including 165file locks (see 166.Fn fcntl ) , 167remain unchanged. 168.It 169The signal mask, signal default actions, and the effective user and 170group IDs for the child process are changed as specified in the 171attributes object referenced by 172.Fa attrp . 173.It 174The file actions specified by the spawn file actions object are 175performed in the order in which they were added to the spawn file 176actions object. 177.It 178Any file descriptor that has its 179.Dv FD_CLOEXEC 180flag set (see 181.Fn fcntl ) 182is closed. 183.El 184.Pp 185The maximum number of 186.Fa file_actions 187objects is limited to the 188.Dv RLIMIT_NOFILE 189rlimit times 2. 190.Pp 191The 192.Vt posix_spawnattr_t 193spawn attributes object type is defined in 194.In spawn.h . 195It contains the attributes defined below. 196.Pp 197If the 198.Dv POSIX_SPAWN_SETPGROUP 199flag is set in the spawn-flags attribute of the object referenced by 200.Fa attrp , 201and the spawn-pgroup attribute of the same object is non-zero, then the 202child's process group is as specified in the spawn-pgroup 203attribute of the object referenced by 204.Fa attrp . 205.Pp 206As a special case, if the 207.Dv POSIX_SPAWN_SETPGROUP 208flag is set in the spawn-flags attribute of the object referenced by 209.Fa attrp , 210and the spawn-pgroup attribute of the same object is set to zero, then 211the child is in a new process group with a process group ID equal 212to its process ID. 213.Pp 214If the 215.Dv POSIX_SPAWN_SETPGROUP 216flag is not set in the spawn-flags attribute of the object referenced by 217.Fa attrp , 218the new child process inherits the parent's process group. 219.Pp 220If the 221.Dv POSIX_SPAWN_SETSCHEDPARAM 222flag is set in the spawn-flags attribute of the object referenced by 223.Fa attrp , 224but 225.Dv POSIX_SPAWN_SETSCHEDULER 226is not set, the new process image initially has the scheduling 227policy of the calling process with the scheduling parameters specified 228in the spawn-schedparam attribute of the object referenced by 229.Fa attrp . 230.Pp 231If the 232.Dv POSIX_SPAWN_SETSCHEDULER 233flag is set in the spawn-flags attribute of the object referenced by 234.Fa attrp 235(regardless of the setting of the 236.Dv POSIX_SPAWN_SETSCHEDPARAM 237flag), the new process image initially has the scheduling policy 238specified in the spawn-schedpolicy attribute of the object referenced by 239.Fa attrp 240and the scheduling parameters specified in the spawn-schedparam 241attribute of the same object. 242.Pp 243The 244.Dv POSIX_SPAWN_RESETIDS 245flag in the spawn-flags attribute of the object referenced by 246.Fa attrp 247governs the effective user ID of the child process. 248If this flag is not set, the child process inherits the parent 249process' effective user ID. 250If this flag is set, the child process' effective user ID is reset 251to the parent's real user ID. 252In either case, if the set-user-ID mode bit of the new process image 253file is set, the effective user ID of the child process becomes 254that file's owner ID before the new process image begins execution. 255.Pp 256The 257.Dv POSIX_SPAWN_RESETIDS 258flag in the spawn-flags attribute of the object referenced by 259.Fa attrp 260also governs the effective group ID of the child process. 261If this flag is not set, the child process inherits the parent 262process' effective group ID. 263If this flag is set, the child process' effective group ID is 264reset to the parent's real group ID. 265In either case, if the set-group-ID mode bit of the new process image 266file is set, the effective group ID of the child process becomes 267that file's group ID before the new process image begins execution. 268.Pp 269If the 270.Dv POSIX_SPAWN_SETSIGMASK 271flag is set in the spawn-flags attribute of the object referenced by 272.Fa attrp , 273the child process initially has the signal mask specified in the 274spawn-sigmask attribute of the object referenced by 275.Fa attrp . 276.Pp 277If the 278.Dv POSIX_SPAWN_SETSIGDEF 279flag is set in the spawn-flags attribute of the object referenced by 280.Fa attrp , 281the signals specified in the spawn-sigdefault attribute of the same 282object is set to their default actions in the child process. 283Signals set to the default action in the parent process is set to 284the default action in the child process. 285.Pp 286Signals set to be caught by the calling process is set to the 287default action in the child process. 288.Pp 289Signals set to be ignored by the calling process image is set to 290be ignored by the child process, unless otherwise specified by the 291.Dv POSIX_SPAWN_SETSIGDEF 292flag being set in the spawn-flags attribute of the object referenced by 293.Fa attrp 294and the signals being indicated in the spawn-sigdefault attribute 295of the object referenced by 296.Fa attrp . 297.Pp 298If the value of the 299.Fa attrp 300pointer is 301.Dv NULL , 302then 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 315This implementation does not run 316.Xr pthread_atfork 3 317callbacks. 318.Fn posix_spawn 319on 320.Nx 321directly creates the child process without intermediate fork. 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 329.Pf non- Dv NULL 330.Fa pid 331argument, and return zero as the function return value. 332Otherwise, no child process is created, no value is stored into 333the variable pointed to by 334.Fa pid , 335and an error number is returned as the function return value to 336indicate the error. 337If the 338.Fa pid 339argument is a null pointer, the process ID of the child is not returned 340to the caller. 341.Sh ERRORS 342.Bl -enum 343.It 344If 345.Fn posix_spawn 346and 347.Fn posix_spawnp 348fail for any of the reasons that would cause 349.Fn vfork 350or one of the 351.Nm exec 352to fail, an error value is returned as described by 353.Fn vfork 354and 355.Nm exec , 356respectively (or, if the error occurs after the calling process successfully 357returns, the child process exits with exit status 127). 358.It 359If 360.Nm POSIX_SPAWN_SETPGROUP 361is set in the spawn-flags attribute of the object referenced by attrp, and 362.Fn posix_spawn 363or 364.Fn posix_spawnp 365fails while changing the child's process group, an error value is returned as 366described by 367.Fn setpgid 368(or, if the error occurs after the calling process successfully returns, 369the child process exits with exit status 127). 370.It 371If 372.Nm POSIX_SPAWN_SETSCHEDPARAM 373is set and 374.Nm POSIX_SPAWN_SETSCHEDULER 375is not set in the spawn-flags attribute of the object referenced by attrp, then 376if 377.Fn posix_spawn 378or 379.Fn posix_spawnp 380fails for any of the reasons that would cause 381.Fn sched_setparam 382to fail, an error value is returned as described by 383.Fn sched_setparam 384(or, if the error occurs after the calling process successfully returns, the 385child process exits with exit status 127). 386.It 387If 388.Nm POSIX_SPAWN_SETSCHEDULER 389is set in the spawn-flags attribute of the object referenced by attrp, and if 390.Fn posix_spawn 391or 392.Fn posix_spawnp 393fails for any of the reasons that would cause 394.Fn sched_setscheduler 395to fail, an error value is returned as described by 396.Fn sched_setscheduler 397(or, if the error occurs after the calling process successfully returns, 398the child process exits with exit status 127). 399.It 400If the 401.Fa file_actions 402argument is not 403.Dv NULL , 404and specifies any 405.Fn close , 406.Fn dup2 , 407or 408.Fn open 409actions to be performed, and if 410.Fn posix_spawn 411or 412.Fn posix_spawnp 413fails for any of the reasons that would cause 414.Fn close , 415.Fn dup2 , 416or 417.Fn open 418to fail, an error value is returned as described by 419.Fn close , 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 close 427or 428.Fn dup2 , 429in addition to those described by 430.Fn open . 431Finally, if the number of 432.Fa file_actions 433objects exceeds the allowed limit, 434.Er EINVAL 435is returned. 436.El 437.Sh SEE ALSO 438.Xr close 2 , 439.Xr dup2 2 , 440.Xr execve 2 , 441.Xr fcntl 2 , 442.Xr open 2 , 443.Xr setpgid 2 , 444.Xr vfork 2 , 445.Xr posix_spawn_file_actions_addchdir 3 , 446.Xr posix_spawn_file_actions_addclose 3 , 447.Xr posix_spawn_file_actions_adddup2 3 , 448.Xr posix_spawn_file_actions_addfchdir 3 , 449.Xr posix_spawn_file_actions_addopen 3 , 450.Xr posix_spawn_file_actions_destroy 3 , 451.Xr posix_spawn_file_actions_init 3 , 452.Xr posix_spawnattr_destroy 3 , 453.Xr posix_spawnattr_getflags 3 , 454.Xr posix_spawnattr_getpgroup 3 , 455.Xr posix_spawnattr_getschedparam 3 , 456.Xr posix_spawnattr_getschedpolicy 3 , 457.Xr posix_spawnattr_getsigdefault 3 , 458.Xr posix_spawnattr_getsigmask 3 , 459.Xr posix_spawnattr_init 3 , 460.Xr posix_spawnattr_setflags 3 , 461.Xr posix_spawnattr_setpgroup 3 , 462.Xr posix_spawnattr_setschedparam 3 , 463.Xr posix_spawnattr_setschedpolicy 3 , 464.Xr posix_spawnattr_setsigdefault 3 , 465.Xr posix_spawnattr_setsigmask 3 , 466.Xr sched_setparam 3 , 467.Xr sched_setscheduler 3 468.Sh STANDARDS 469The 470.Fn posix_spawn 471and 472.Fn posix_spawnp 473functions conform to 474.St -p1003.1-2001 . 475.Sh HISTORY 476The 477.Fn posix_spawn 478and 479.Fn posix_spawnp 480functions first appeared in 481.Fx 8.0 . 482The library parts were ported and a kernel implementation of 483.Fn posix_spawn 484added for 485.Nx 6.0 486during Google Summer of Code by Charles Zhang and Martin Husemann. 487.Sh AUTHORS 488.An \&Ed Schouten Aq Mt ed@FreeBSD.org 489