xref: /freebsd/lib/libc/gen/posix_spawn.3 (revision 2c96ea9ca0aa37db109700be5ed33afc30133ec1)
162187b41SDavid Xu.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
262187b41SDavid Xu.\" All rights reserved.
362187b41SDavid Xu.\"
462187b41SDavid Xu.\" Redistribution and use in source and binary forms, with or without
562187b41SDavid Xu.\" modification, are permitted provided that the following conditions
662187b41SDavid Xu.\" are met:
762187b41SDavid Xu.\" 1. Redistributions of source code must retain the above copyright
862187b41SDavid Xu.\"    notice, this list of conditions and the following disclaimer.
962187b41SDavid Xu.\" 2. Redistributions in binary form must reproduce the above copyright
1062187b41SDavid Xu.\"    notice, this list of conditions and the following disclaimer in the
1162187b41SDavid Xu.\"    documentation and/or other materials provided with the distribution.
1262187b41SDavid Xu.\"
1362187b41SDavid Xu.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
1462187b41SDavid Xu.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1562187b41SDavid Xu.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1662187b41SDavid Xu.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
1762187b41SDavid Xu.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1862187b41SDavid Xu.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
1962187b41SDavid Xu.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2062187b41SDavid Xu.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2162187b41SDavid Xu.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2262187b41SDavid Xu.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
2362187b41SDavid Xu.\" SUCH DAMAGE.
2462187b41SDavid Xu.\"
2562187b41SDavid Xu.\" Portions of this text are reprinted and reproduced in electronic form
2662187b41SDavid Xu.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
2762187b41SDavid Xu.\" Portable Operating System Interface (POSIX), The Open Group Base
2862187b41SDavid Xu.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
2962187b41SDavid Xu.\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
3062187b41SDavid Xu.\" event of any discrepancy between this version and the original IEEE and
3162187b41SDavid Xu.\" The Open Group Standard, the original IEEE and The Open Group Standard is
3262187b41SDavid Xu.\" the referee document.  The original Standard can be obtained online at
3362187b41SDavid Xu.\"	http://www.opengroup.org/unix/online.html.
3462187b41SDavid Xu.\"
3562187b41SDavid Xu.\" $FreeBSD$
3662187b41SDavid Xu.\"
3743d53dbaSJilles Tjoelker.Dd January 5, 2016
3862187b41SDavid Xu.Dt POSIX_SPAWN 3
3962187b41SDavid Xu.Os
4062187b41SDavid Xu.Sh NAME
4162187b41SDavid Xu.Nm posix_spawn ,
4262187b41SDavid Xu.Nm posix_spawnp
4362187b41SDavid Xu.Nd "spawn a process"
4462187b41SDavid Xu.Sh LIBRARY
4562187b41SDavid Xu.Lb libc
4662187b41SDavid Xu.Sh SYNOPSIS
4762187b41SDavid Xu.In spawn.h
4862187b41SDavid Xu.Ft int
4962187b41SDavid Xu.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]"
5062187b41SDavid Xu.Ft int
5162187b41SDavid Xu.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]"
5262187b41SDavid Xu.Sh DESCRIPTION
5362187b41SDavid XuThe
5462187b41SDavid Xu.Fn posix_spawn
5562187b41SDavid Xuand
5662187b41SDavid Xu.Fn posix_spawnp
5762187b41SDavid Xufunctions create a new process (child process) from the specified
5862187b41SDavid Xuprocess image.
5962187b41SDavid XuThe new process image is constructed from a regular executable
6062187b41SDavid Xufile called the new process image file.
6162187b41SDavid Xu.Pp
6262187b41SDavid XuWhen a C program is executed as the result of this call, it is
6362187b41SDavid Xuentered as a C-language function call as follows:
6462187b41SDavid Xu.Bd -literal -offset indent
6562187b41SDavid Xuint main(int argc, char *argv[]);
6662187b41SDavid Xu.Ed
6762187b41SDavid Xu.Pp
6862187b41SDavid Xuwhere
6962187b41SDavid Xu.Fa argc
7062187b41SDavid Xuis the argument count and
7162187b41SDavid Xu.Fa argv
7262187b41SDavid Xuis an array of character pointers to the arguments themselves.
7362187b41SDavid XuIn addition, the variable:
7462187b41SDavid Xu.Bd -literal -offset indent
7562187b41SDavid Xuextern char **environ;
7662187b41SDavid Xu.Ed
7762187b41SDavid Xu.Pp
7862187b41SDavid Xupoints to an array of character pointers to
7962187b41SDavid Xuthe environment strings.
8062187b41SDavid Xu.Pp
8162187b41SDavid XuThe argument
8262187b41SDavid Xu.Fa argv
8362187b41SDavid Xuis an array of character pointers to null-terminated
8462187b41SDavid Xustrings.
8562187b41SDavid XuThe last member of this array is a null pointer and is not counted
8662187b41SDavid Xuin
8762187b41SDavid Xu.Fa argc .
8862187b41SDavid XuThese strings constitute the argument list available to the new process
8962187b41SDavid Xuimage.
9062187b41SDavid XuThe value in
9162187b41SDavid Xu.Fa argv Ns [0]
9262187b41SDavid Xushould point to
9362187b41SDavid Xua filename that is associated with the process image being started by
9462187b41SDavid Xuthe
9562187b41SDavid Xu.Fn posix_spawn
9662187b41SDavid Xuor
9762187b41SDavid Xu.Fn posix_spawnp
9862187b41SDavid Xufunction.
9962187b41SDavid Xu.Pp
10062187b41SDavid XuThe argument
10162187b41SDavid Xu.Fa envp
10262187b41SDavid Xuis an array of character pointers to null-terminated strings.
10362187b41SDavid XuThese strings constitute the environment for the new process image.
10462187b41SDavid XuThe environment array is terminated by a null pointer.
10562187b41SDavid Xu.Pp
10662187b41SDavid XuThe
10762187b41SDavid Xu.Fa path
10862187b41SDavid Xuargument to
10962187b41SDavid Xu.Fn posix_spawn
11062187b41SDavid Xuis a pathname that identifies the new process image file to execute.
11162187b41SDavid Xu.Pp
11262187b41SDavid XuThe
11362187b41SDavid Xu.Fa file
11462187b41SDavid Xuparameter to
11562187b41SDavid Xu.Fn posix_spawnp
11662187b41SDavid Xuis used to construct a pathname that identifies the new process
11762187b41SDavid Xuimage file.
11862187b41SDavid XuIf the file parameter contains a slash character, the file parameter
11962187b41SDavid Xuis used as the pathname for the new process image file.
12062187b41SDavid XuOtherwise, the path prefix for this file is obtained by a search
12162187b41SDavid Xuof the directories passed as the environment variable
12262187b41SDavid Xu.Dq Ev PATH .
12362187b41SDavid XuIf this variable is not specified,
12462187b41SDavid Xuthe default path is set according to the
12562187b41SDavid Xu.Dv _PATH_DEFPATH
12662187b41SDavid Xudefinition in
12762187b41SDavid Xu.In paths.h ,
12862187b41SDavid Xuwhich is set to
12943d53dbaSJilles Tjoelker.Dq Ev /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
13062187b41SDavid Xu.Pp
13162187b41SDavid XuIf
13262187b41SDavid Xu.Fa file_actions
13362187b41SDavid Xuis a null pointer, then file descriptors open in the
13462187b41SDavid Xucalling process remain open in the child process, except for those
13562187b41SDavid Xuwhose close-on-exec flag
13662187b41SDavid Xu.Dv FD_CLOEXEC
13762187b41SDavid Xuis set (see
13862187b41SDavid Xu.Fn fcntl ) .
13962187b41SDavid XuFor those
14062187b41SDavid Xufile descriptors that remain open, all attributes of the corresponding
14162187b41SDavid Xuopen file descriptions, including file locks (see
14262187b41SDavid Xu.Fn fcntl ) ,
14362187b41SDavid Xuremain unchanged.
14462187b41SDavid Xu.Pp
14562187b41SDavid XuIf
14662187b41SDavid Xu.Fa file_actions
14762187b41SDavid Xuis not NULL, then the file descriptors open in the child process are
14862187b41SDavid Xuthose open in the calling process as modified by the spawn file
14962187b41SDavid Xuactions object pointed to by
15062187b41SDavid Xu.Fa file_actions
15162187b41SDavid Xuand the
15262187b41SDavid Xu.Dv FD_CLOEXEC
15362187b41SDavid Xuflag of each remaining open file descriptor after the spawn file actions
15462187b41SDavid Xuhave been processed.
15562187b41SDavid XuThe effective order of processing the spawn file actions are:
15662187b41SDavid Xu.Bl -enum
15762187b41SDavid Xu.It
15862187b41SDavid XuThe set of open file descriptors for the child process initially
15962187b41SDavid Xuare the same set as is open for the calling process.
16062187b41SDavid XuAll attributes of the corresponding open file descriptions, including
16162187b41SDavid Xufile locks (see
16262187b41SDavid Xu.Fn fcntl ) ,
16362187b41SDavid Xuremain unchanged.
16462187b41SDavid Xu.It
16562187b41SDavid XuThe signal mask, signal default actions, and the effective user and
16662187b41SDavid Xugroup IDs for the child process are changed as specified in the
16762187b41SDavid Xuattributes object referenced by
16862187b41SDavid Xu.Fa attrp .
16962187b41SDavid Xu.It
17062187b41SDavid XuThe file actions specified by the spawn file actions object are
17162187b41SDavid Xuperformed in the order in which they were added to the spawn file
17262187b41SDavid Xuactions object.
17362187b41SDavid Xu.It
17462187b41SDavid XuAny file descriptor that has its
17562187b41SDavid Xu.Dv FD_CLOEXEC
17662187b41SDavid Xuflag set (see
17762187b41SDavid Xu.Fn fcntl )
17862187b41SDavid Xuis closed.
17962187b41SDavid Xu.El
18062187b41SDavid Xu.Pp
18162187b41SDavid XuThe
18262187b41SDavid Xu.Vt posix_spawnattr_t
18362187b41SDavid Xuspawn attributes object type is defined in
18462187b41SDavid Xu.In spawn.h .
18562187b41SDavid XuIt contains the attributes defined below.
18662187b41SDavid Xu.Pp
18762187b41SDavid XuIf the
18862187b41SDavid Xu.Dv POSIX_SPAWN_SETPGROUP
18962187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
19062187b41SDavid Xu.Fa attrp ,
19162187b41SDavid Xuand the spawn-pgroup attribute of the same object is non-zero, then the
19262187b41SDavid Xuchild's process group is as specified in the spawn-pgroup
19362187b41SDavid Xuattribute of the object referenced by
19462187b41SDavid Xu.Fa attrp .
19562187b41SDavid Xu.Pp
19662187b41SDavid XuAs a special case, if the
19762187b41SDavid Xu.Dv POSIX_SPAWN_SETPGROUP
19862187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
19962187b41SDavid Xu.Fa attrp ,
20062187b41SDavid Xuand the spawn-pgroup attribute of the same object is set to zero, then
20162187b41SDavid Xuthe child is in a new process group with a process group ID equal
20262187b41SDavid Xuto its process ID.
20362187b41SDavid Xu.Pp
20462187b41SDavid XuIf the
20562187b41SDavid Xu.Dv POSIX_SPAWN_SETPGROUP
20662187b41SDavid Xuflag is not set in the spawn-flags attribute of the object referenced by
20762187b41SDavid Xu.Fa attrp ,
20862187b41SDavid Xuthe new child process inherits the parent's process group.
20962187b41SDavid Xu.Pp
21062187b41SDavid XuIf the
21162187b41SDavid Xu.Dv POSIX_SPAWN_SETSCHEDPARAM
21262187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
21362187b41SDavid Xu.Fa attrp ,
21462187b41SDavid Xubut
21562187b41SDavid Xu.Dv POSIX_SPAWN_SETSCHEDULER
21662187b41SDavid Xuis not set, the new process image initially has the scheduling
21762187b41SDavid Xupolicy of the calling process with the scheduling parameters specified
21862187b41SDavid Xuin the spawn-schedparam attribute of the object referenced by
21962187b41SDavid Xu.Fa attrp .
22062187b41SDavid Xu.Pp
22162187b41SDavid XuIf the
22262187b41SDavid Xu.Dv POSIX_SPAWN_SETSCHEDULER
22362187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
22462187b41SDavid Xu.Fa attrp
22562187b41SDavid Xu(regardless of the setting of the
22662187b41SDavid Xu.Dv POSIX_SPAWN_SETSCHEDPARAM
22762187b41SDavid Xuflag), the new process image initially has the scheduling policy
22862187b41SDavid Xuspecified in the spawn-schedpolicy attribute of the object referenced by
22962187b41SDavid Xu.Fa attrp
23062187b41SDavid Xuand the scheduling parameters specified in the spawn-schedparam
23162187b41SDavid Xuattribute of the same object.
23262187b41SDavid Xu.Pp
23362187b41SDavid XuThe
23462187b41SDavid Xu.Dv POSIX_SPAWN_RESETIDS
23562187b41SDavid Xuflag in the spawn-flags attribute of the object referenced by
23662187b41SDavid Xu.Fa attrp
23762187b41SDavid Xugoverns the effective user ID of the child process.
23862187b41SDavid XuIf this flag is not set, the child process inherits the parent
23962187b41SDavid Xuprocess' effective user ID.
24062187b41SDavid XuIf this flag is set, the child process' effective user ID is reset
24162187b41SDavid Xuto the parent's real user ID.
24262187b41SDavid XuIn either case, if the set-user-ID mode bit of the new process image
24362187b41SDavid Xufile is set, the effective user ID of the child process becomes
24462187b41SDavid Xuthat file's owner ID before the new process image begins execution.
24562187b41SDavid Xu.Pp
24662187b41SDavid XuThe
24762187b41SDavid Xu.Dv POSIX_SPAWN_RESETIDS
24862187b41SDavid Xuflag in the spawn-flags attribute of the object referenced by
24962187b41SDavid Xu.Fa attrp
25062187b41SDavid Xualso governs the effective group ID of the child process.
25162187b41SDavid XuIf this flag is not set, the child process inherits the parent
25262187b41SDavid Xuprocess' effective group ID.
25362187b41SDavid XuIf this flag is set, the child process' effective group ID is
25462187b41SDavid Xureset to the parent's real group ID.
25562187b41SDavid XuIn either case, if the set-group-ID mode bit of the new process image
25662187b41SDavid Xufile is set, the effective group ID of the child process becomes
25762187b41SDavid Xuthat file's group ID before the new process image begins execution.
25862187b41SDavid Xu.Pp
25962187b41SDavid XuIf the
26062187b41SDavid Xu.Dv POSIX_SPAWN_SETSIGMASK
26162187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
26262187b41SDavid Xu.Fa attrp ,
26362187b41SDavid Xuthe child process initially has the signal mask specified in the
26462187b41SDavid Xuspawn-sigmask attribute of the object referenced by
26562187b41SDavid Xu.Fa attrp .
26662187b41SDavid Xu.Pp
26762187b41SDavid XuIf the
26862187b41SDavid Xu.Dv POSIX_SPAWN_SETSIGDEF
26962187b41SDavid Xuflag is set in the spawn-flags attribute of the object referenced by
27062187b41SDavid Xu.Fa attrp ,
27162187b41SDavid Xuthe signals specified in the spawn-sigdefault attribute of the same
2728d55975fSBryan Dreweryobject are set to their default actions in the child process.
2738d55975fSBryan DrewerySignals set to the default action in the parent process are set to
27462187b41SDavid Xuthe default action in the child process.
27562187b41SDavid Xu.Pp
2768d55975fSBryan DrewerySignals set to be caught by the calling process are set to the
27762187b41SDavid Xudefault action in the child process.
27862187b41SDavid Xu.Pp
2798d55975fSBryan DrewerySignals set to be ignored by the calling process image are set to
28062187b41SDavid Xube ignored by the child process, unless otherwise specified by the
28162187b41SDavid Xu.Dv POSIX_SPAWN_SETSIGDEF
28262187b41SDavid Xuflag being set in the spawn-flags attribute of the object referenced by
28362187b41SDavid Xu.Fa attrp
28462187b41SDavid Xuand the signals being indicated in the spawn-sigdefault attribute
28562187b41SDavid Xuof the object referenced by
28662187b41SDavid Xu.Fa attrp .
28762187b41SDavid Xu.Pp
28862187b41SDavid XuIf the value of the
28962187b41SDavid Xu.Fa attrp
29062187b41SDavid Xupointer is NULL, then the default values are used.
29162187b41SDavid Xu.Pp
29262187b41SDavid XuAll process attributes, other than those influenced by the attributes
29362187b41SDavid Xuset in the object referenced by
29462187b41SDavid Xu.Fa attrp
29562187b41SDavid Xuas specified above or by the file descriptor manipulations specified in
29662187b41SDavid Xu.Fa file_actions ,
29762187b41SDavid Xuappear in the new process image as though
29862187b41SDavid Xu.Fn vfork
29962187b41SDavid Xuhad been called to create a child process and then
30062187b41SDavid Xu.Fn execve
30162187b41SDavid Xuhad been called by the child process to execute the new process image.
30262187b41SDavid Xu.Pp
303*2c96ea9cSEnji CooperThe implementation uses
304*2c96ea9cSEnji Cooper.Fn vfork ,
305*2c96ea9cSEnji Cooperthus the fork handlers are not run when
30662187b41SDavid Xu.Fn posix_spawn
30762187b41SDavid Xuor
30862187b41SDavid Xu.Fn posix_spawnp
30962187b41SDavid Xuis called.
31062187b41SDavid Xu.Sh RETURN VALUES
31162187b41SDavid XuUpon successful completion,
31262187b41SDavid Xu.Fn posix_spawn
31362187b41SDavid Xuand
31462187b41SDavid Xu.Fn posix_spawnp
31562187b41SDavid Xureturn the process ID of the child process to the parent process,
31662187b41SDavid Xuin the variable pointed to by a non-NULL
31762187b41SDavid Xu.Fa pid
31862187b41SDavid Xuargument, and return zero as the function return value.
31962187b41SDavid XuOtherwise, no child process is created, no value is stored into
32062187b41SDavid Xuthe variable pointed to by
32162187b41SDavid Xu.Fa pid ,
32262187b41SDavid Xuand an error number is returned as the function return value to
32362187b41SDavid Xuindicate the error.
32462187b41SDavid XuIf the
32562187b41SDavid Xu.Fa pid
32662187b41SDavid Xuargument is a null pointer, the process ID of the child is not returned
32762187b41SDavid Xuto the caller.
32862187b41SDavid Xu.Sh ERRORS
32962187b41SDavid Xu.Bl -enum
33062187b41SDavid Xu.It
33162187b41SDavid XuIf
33262187b41SDavid Xu.Fn posix_spawn
33362187b41SDavid Xuand
33462187b41SDavid Xu.Fn posix_spawnp
33562187b41SDavid Xufail for any of the reasons that would cause
33662187b41SDavid Xu.Fn vfork
33762187b41SDavid Xuor one of the
33862187b41SDavid Xu.Nm exec
33962187b41SDavid Xuto fail, an error value is returned as described by
34062187b41SDavid Xu.Fn vfork
34162187b41SDavid Xuand
34262187b41SDavid Xu.Nm exec ,
34362187b41SDavid Xurespectively (or, if the error occurs after the calling process successfully
34462187b41SDavid Xureturns, the child process exits with exit status 127).
34562187b41SDavid Xu.It
34662187b41SDavid XuIf
34762187b41SDavid Xu.Nm POSIX_SPAWN_SETPGROUP
34862187b41SDavid Xuis set in the spawn-flags attribute of the object referenced by attrp, and
34962187b41SDavid Xu.Fn posix_spawn
35062187b41SDavid Xuor
35162187b41SDavid Xu.Fn posix_spawnp
35262187b41SDavid Xufails while changing the child's process group, an error value is returned as
35362187b41SDavid Xudescribed by
35462187b41SDavid Xu.Fn setpgid
35562187b41SDavid Xu(or, if the error occurs after the calling process successfully returns,
35662187b41SDavid Xuthe child process exits with exit status 127).
35762187b41SDavid Xu.It
35862187b41SDavid XuIf
35962187b41SDavid Xu.Nm POSIX_SPAWN_SETSCHEDPARAM
36062187b41SDavid Xuis set and
36162187b41SDavid Xu.Nm POSIX_SPAWN_SETSCHEDULER
36262187b41SDavid Xuis not set in the spawn-flags attribute of the object referenced by attrp, then
36362187b41SDavid Xuif
36462187b41SDavid Xu.Fn posix_spawn
36562187b41SDavid Xuor
36662187b41SDavid Xu.Fn posix_spawnp
36762187b41SDavid Xufails for any of the reasons that would cause
36862187b41SDavid Xu.Fn sched_setparam
36962187b41SDavid Xuto fail, an error value is returned as described by
37062187b41SDavid Xu.Fn sched_setparam
37162187b41SDavid Xu(or, if the error occurs after the calling process successfully returns, the
37262187b41SDavid Xuchild process exits with exit status 127).
37362187b41SDavid Xu.It
37462187b41SDavid XuIf
37562187b41SDavid Xu.Nm POSIX_SPAWN_SETSCHEDULER
37662187b41SDavid Xuis set in the spawn-flags attribute of the object referenced by attrp, and if
37762187b41SDavid Xu.Fn posix_spawn
37862187b41SDavid Xuor
37962187b41SDavid Xu.Fn posix_spawnp
38062187b41SDavid Xufails for any of the reasons that would cause
38162187b41SDavid Xu.Fn sched_setscheduler
38262187b41SDavid Xuto fail, an error value is returned as described by
38362187b41SDavid Xu.Fn sched_setscheduler
38462187b41SDavid Xu(or, if the error occurs after the calling process successfully returns,
38562187b41SDavid Xuthe child process exits with exit status 127).
38662187b41SDavid Xu.It
38762187b41SDavid XuIf the
38862187b41SDavid Xu.Fa file_actions
389876b6796SJilles Tjoelkerargument is not NULL, and specifies any dup2 or open actions to be
39062187b41SDavid Xuperformed, and if
39162187b41SDavid Xu.Fn posix_spawn
39262187b41SDavid Xuor
39362187b41SDavid Xu.Fn posix_spawnp
39462187b41SDavid Xufails for any of the reasons that would cause
395876b6796SJilles Tjoelker.Fn dup2
39662187b41SDavid Xuor
39762187b41SDavid Xu.Fn open
39862187b41SDavid Xuto fail, an error value is returned as described by
399876b6796SJilles Tjoelker.Fn dup2
40062187b41SDavid Xuand
40162187b41SDavid Xu.Fn open ,
40262187b41SDavid Xurespectively (or, if the error occurs after the calling process successfully
40362187b41SDavid Xureturns, the child process exits with exit status 127). An open file action
40462187b41SDavid Xumay, by itself, result in any of the errors described by
40562187b41SDavid Xu.Fn dup2 ,
40662187b41SDavid Xuin addition to those described by
40762187b41SDavid Xu.Fn open .
408876b6796SJilles TjoelkerThis implementation ignores any errors from
409876b6796SJilles Tjoelker.Fn close ,
410876b6796SJilles Tjoelkerincluding trying to close a descriptor that is not open.
41162187b41SDavid Xu.El
41262187b41SDavid Xu.Sh SEE ALSO
41362187b41SDavid Xu.Xr close 2 ,
41462187b41SDavid Xu.Xr dup2 2 ,
41562187b41SDavid Xu.Xr execve 2 ,
41662187b41SDavid Xu.Xr fcntl 2 ,
41762187b41SDavid Xu.Xr open 2 ,
4180aee91e1SChristian Brueffer.Xr sched_setparam 2 ,
4190aee91e1SChristian Brueffer.Xr sched_setscheduler 2 ,
4200aee91e1SChristian Brueffer.Xr setpgid 2 ,
4210aee91e1SChristian Brueffer.Xr vfork 2 ,
42262187b41SDavid Xu.Xr posix_spawn_file_actions_addclose 3 ,
42362187b41SDavid Xu.Xr posix_spawn_file_actions_adddup2 3 ,
42462187b41SDavid Xu.Xr posix_spawn_file_actions_addopen 3 ,
42562187b41SDavid Xu.Xr posix_spawn_file_actions_destroy 3 ,
42662187b41SDavid Xu.Xr posix_spawn_file_actions_init 3 ,
42762187b41SDavid Xu.Xr posix_spawnattr_destroy 3 ,
42862187b41SDavid Xu.Xr posix_spawnattr_getflags 3 ,
42962187b41SDavid Xu.Xr posix_spawnattr_getpgroup 3 ,
43062187b41SDavid Xu.Xr posix_spawnattr_getschedparam 3 ,
43162187b41SDavid Xu.Xr posix_spawnattr_getschedpolicy 3 ,
43262187b41SDavid Xu.Xr posix_spawnattr_getsigdefault 3 ,
43362187b41SDavid Xu.Xr posix_spawnattr_getsigmask 3 ,
43462187b41SDavid Xu.Xr posix_spawnattr_init 3 ,
43562187b41SDavid Xu.Xr posix_spawnattr_setflags 3 ,
43662187b41SDavid Xu.Xr posix_spawnattr_setpgroup 3 ,
43762187b41SDavid Xu.Xr posix_spawnattr_setschedparam 3 ,
43862187b41SDavid Xu.Xr posix_spawnattr_setschedpolicy 3 ,
43962187b41SDavid Xu.Xr posix_spawnattr_setsigdefault 3 ,
4400aee91e1SChristian Brueffer.Xr posix_spawnattr_setsigmask 3
44162187b41SDavid Xu.Sh STANDARDS
44262187b41SDavid XuThe
44362187b41SDavid Xu.Fn posix_spawn
44462187b41SDavid Xuand
44562187b41SDavid Xu.Fn posix_spawnp
44662187b41SDavid Xufunctions conform to
447876b6796SJilles Tjoelker.St -p1003.1-2001 ,
448876b6796SJilles Tjoelkerexcept that they ignore all errors from
449876b6796SJilles Tjoelker.Fn close .
450876b6796SJilles TjoelkerA future update of the Standard is expected to require that these functions
451876b6796SJilles Tjoelkernot fail because a file descriptor to be closed (via
452876b6796SJilles Tjoelker.Fn posix_spawn_file_actions_addclose )
453876b6796SJilles Tjoelkeris not open.
45462187b41SDavid Xu.Sh HISTORY
45562187b41SDavid XuThe
45662187b41SDavid Xu.Fn posix_spawn
45762187b41SDavid Xuand
45862187b41SDavid Xu.Fn posix_spawnp
45962187b41SDavid Xufunctions first appeared in
46062187b41SDavid Xu.Fx 8.0 .
46162187b41SDavid Xu.Sh AUTHORS
46218c5321dSBaptiste Daroussin.An \&Ed Schouten Aq Mt ed@FreeBSD.org
463