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