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: src/lib/libc/gen/posix_spawn.3,v 1.2 2008/07/28 09:36:56 ed Exp $ 36.\" 37.Dd April 7, 2009 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 304.Fn vfork , 305thus the fork handlers are not run when 306.Fn posix_spawn 307or 308.Fn posix_spawnp 309is called. 310.Sh RETURN VALUES 311Upon successful completion, 312.Fn posix_spawn 313and 314.Fn posix_spawnp 315return the process ID of the child process to the parent process, 316in the variable pointed to by a non-NULL 317.Fa pid 318argument, and return zero as the function return value. 319Otherwise, no child process is created, no value is stored into 320the variable pointed to by 321.Fa pid , 322and an error number is returned as the function return value to 323indicate the error. 324If the 325.Fa pid 326argument is a null pointer, the process ID of the child is not returned 327to the caller. 328.Sh ERRORS 329.Bl -enum 330.It 331If 332.Fn posix_spawn 333and 334.Fn posix_spawnp 335fail for any of the reasons that would cause 336.Fn vfork 337or one of the 338.Nm exec 339to fail, an error value is returned as described by 340.Fn vfork 341and 342.Nm exec , 343respectively (or, if the error occurs after the calling process successfully 344returns, the child process exits with exit status 127). 345.It 346If 347.Dv POSIX_SPAWN_SETPGROUP 348is set in the spawn-flags attribute of the object referenced by attrp, and 349.Fn posix_spawn 350or 351.Fn posix_spawnp 352fails while changing the child's process group, an error value is returned as 353described by 354.Fn setpgid 355(or, if the error occurs after the calling process successfully returns, 356the child process exits with exit status 127). 357.It 358If 359.Dv POSIX_SPAWN_SETSCHEDPARAM 360is set and 361.Dv POSIX_SPAWN_SETSCHEDULER 362is not set in the spawn-flags attribute of the object referenced by attrp, then 363if 364.Fn posix_spawn 365or 366.Fn posix_spawnp 367fails for any of the reasons that would cause 368.Fn sched_setparam 369to fail, an error value is returned as described by 370.Fn sched_setparam 371(or, if the error occurs after the calling process successfully returns, the 372child process exits with exit status 127). 373.It 374If 375.Dv POSIX_SPAWN_SETSCHEDULER 376is set in the spawn-flags attribute of the object referenced by attrp, and if 377.Fn posix_spawn 378or 379.Fn posix_spawnp 380fails for any of the reasons that would cause 381.Fn sched_setscheduler 382to fail, an error value is returned as described by 383.Fn sched_setscheduler 384(or, if the error occurs after the calling process successfully returns, 385the child process exits with exit status 127). 386.It 387If the 388.Fa file_actions 389argument is not NULL, and specifies any close, dup2, or open actions to be 390performed, and if 391.Fn posix_spawn 392or 393.Fn posix_spawnp 394fails for any of the reasons that would cause 395.Fn close , 396.Fn dup2 , 397or 398.Fn open 399to fail, an error value is returned as described by 400.Fn close , 401.Fn dup2 , 402and 403.Fn open , 404respectively (or, if the error occurs after the calling process successfully 405returns, the child process exits with exit status 127). An open file action 406may, by itself, result in any of the errors described by 407.Fn close 408or 409.Fn dup2 , 410in addition to those described by 411.Fn open . 412.El 413.Sh SEE ALSO 414.Xr close 2 , 415.Xr dup2 2 , 416.Xr execve 2 , 417.Xr fcntl 2 , 418.Xr open 2 , 419.Xr sched_setparam 2 , 420.Xr sched_setscheduler 2 , 421.Xr setpgid 2 , 422.Xr vfork 2 , 423.Xr posix_spawn_file_actions_addclose 3 , 424.Xr posix_spawn_file_actions_adddup2 3 , 425.Xr posix_spawn_file_actions_addopen 3 , 426.Xr posix_spawn_file_actions_destroy 3 , 427.Xr posix_spawn_file_actions_init 3 , 428.Xr posix_spawnattr_destroy 3 , 429.Xr posix_spawnattr_getflags 3 , 430.Xr posix_spawnattr_getpgroup 3 , 431.Xr posix_spawnattr_getschedparam 3 , 432.Xr posix_spawnattr_getschedpolicy 3 , 433.Xr posix_spawnattr_getsigdefault 3 , 434.Xr posix_spawnattr_getsigmask 3 , 435.Xr posix_spawnattr_init 3 , 436.Xr posix_spawnattr_setflags 3 , 437.Xr posix_spawnattr_setpgroup 3 , 438.Xr posix_spawnattr_setschedparam 3 , 439.Xr posix_spawnattr_setschedpolicy 3 , 440.Xr posix_spawnattr_setsigdefault 3 , 441.Xr posix_spawnattr_setsigmask 3 442.Sh STANDARDS 443The 444.Fn posix_spawn 445and 446.Fn posix_spawnp 447functions conform to 448.St -p1003.1-2001 . 449.Sh HISTORY 450The 451.Fn posix_spawn 452and 453.Fn posix_spawnp 454functions first appeared in 455.Fx 8.0 . 456.Sh AUTHORS 457.An \&Ed Schouten Aq Mt ed@FreeBSD.org 458