1.\" $NetBSD: posix_spawn.3,v 1.6 2014/02/02 16:59:06 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 February 2, 2014 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 315The implementation uses vfork(), thus the fork handlers are not run when 316.Fn posix_spawn 317or 318.Fn posix_spawnp 319is called. 320.Sh RETURN VALUES 321Upon successful completion, 322.Fn posix_spawn 323and 324.Fn posix_spawnp 325return the process ID of the child process to the parent process, 326in the variable pointed to by a 327.Pf non- Dv NULL 328.Fa pid 329argument, and return zero as the function return value. 330Otherwise, no child process is created, no value is stored into 331the variable pointed to by 332.Fa pid , 333and an error number is returned as the function return value to 334indicate the error. 335If the 336.Fa pid 337argument is a null pointer, the process ID of the child is not returned 338to the caller. 339.Sh ERRORS 340.Bl -enum 341.It 342If 343.Fn posix_spawn 344and 345.Fn posix_spawnp 346fail for any of the reasons that would cause 347.Fn vfork 348or one of the 349.Nm exec 350to fail, an error value is returned as described by 351.Fn vfork 352and 353.Nm exec , 354respectively (or, if the error occurs after the calling process successfully 355returns, the child process exits with exit status 127). 356.It 357If 358.Nm POSIX_SPAWN_SETPGROUP 359is set in the spawn-flags attribute of the object referenced by attrp, and 360.Fn posix_spawn 361or 362.Fn posix_spawnp 363fails while changing the child's process group, an error value is returned as 364described by 365.Fn setpgid 366(or, if the error occurs after the calling process successfully returns, 367the child process exits with exit status 127). 368.It 369If 370.Nm POSIX_SPAWN_SETSCHEDPARAM 371is set and 372.Nm POSIX_SPAWN_SETSCHEDULER 373is not set in the spawn-flags attribute of the object referenced by attrp, then 374if 375.Fn posix_spawn 376or 377.Fn posix_spawnp 378fails for any of the reasons that would cause 379.Fn sched_setparam 380to fail, an error value is returned as described by 381.Fn sched_setparam 382(or, if the error occurs after the calling process successfully returns, the 383child process exits with exit status 127). 384.It 385If 386.Nm POSIX_SPAWN_SETSCHEDULER 387is set in the spawn-flags attribute of the object referenced by attrp, and if 388.Fn posix_spawn 389or 390.Fn posix_spawnp 391fails for any of the reasons that would cause 392.Fn sched_setscheduler 393to fail, an error value is returned as described by 394.Fn sched_setscheduler 395(or, if the error occurs after the calling process successfully returns, 396the child process exits with exit status 127). 397.It 398If the 399.Fa file_actions 400argument is not 401.Dv NULL , 402and specifies any 403.Fn close , 404.Fn dup2 , 405or 406.Fn open 407actions to be performed, and if 408.Fn posix_spawn 409or 410.Fn posix_spawnp 411fails for any of the reasons that would cause 412.Fn close , 413.Fn dup2 , 414or 415.Fn open 416to fail, an error value is returned as described by 417.Fn close , 418.Fn dup2 , 419and 420.Fn open , 421respectively (or, if the error occurs after the calling process successfully 422returns, the child process exits with exit status 127). An open file action 423may, by itself, result in any of the errors described by 424.Fn close 425or 426.Fn dup2 , 427in addition to those described by 428.Fn open . 429Finally, if the number of 430.Fa file_actions 431objects exceeds the allowed limit, 432.Er EINVAL 433is returned. 434.El 435.Sh SEE ALSO 436.Xr close 2 , 437.Xr dup2 2 , 438.Xr execve 2 , 439.Xr fcntl 2 , 440.Xr open 2 , 441.Xr setpgid 2 , 442.Xr vfork 2 , 443.Xr posix_spawn_file_actions_addclose 3 , 444.Xr posix_spawn_file_actions_adddup2 3 , 445.Xr posix_spawn_file_actions_addopen 3 , 446.Xr posix_spawn_file_actions_destroy 3 , 447.Xr posix_spawn_file_actions_init 3 , 448.Xr posix_spawnattr_destroy 3 , 449.Xr posix_spawnattr_getflags 3 , 450.Xr posix_spawnattr_getpgroup 3 , 451.Xr posix_spawnattr_getschedparam 3 , 452.Xr posix_spawnattr_getschedpolicy 3 , 453.Xr posix_spawnattr_getsigdefault 3 , 454.Xr posix_spawnattr_getsigmask 3 , 455.Xr posix_spawnattr_init 3 , 456.Xr posix_spawnattr_setflags 3 , 457.Xr posix_spawnattr_setpgroup 3 , 458.Xr posix_spawnattr_setschedparam 3 , 459.Xr posix_spawnattr_setschedpolicy 3 , 460.Xr posix_spawnattr_setsigdefault 3 , 461.Xr posix_spawnattr_setsigmask 3 , 462.Xr sched_setparam 3 , 463.Xr sched_setscheduler 3 464.Sh STANDARDS 465The 466.Fn posix_spawn 467and 468.Fn posix_spawnp 469functions conform to 470.St -p1003.1-2001 . 471.Sh HISTORY 472The 473.Fn posix_spawn 474and 475.Fn posix_spawnp 476functions first appeared in 477.Fx 8.0 . 478The library parts were ported and a kernel implementation of 479.Fn posix_spawn 480added for 481.Nx 6.0 482during Google Summer of Code by Charles Zhang and Martin Husemann. 483.Sh AUTHORS 484.An Ed Schouten Aq Mt ed@FreeBSD.org 485