posix_spawn.3p (30054B)
- '\" et
- .TH POSIX_SPAWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- posix_spawn,
- posix_spawnp
- \(em spawn a process
- (\fBADVANCED REALTIME\fP)
- .SH SYNOPSIS
- .LP
- .nf
- #include <spawn.h>
- .P
- int posix_spawn(pid_t *restrict \fIpid\fP, const char *restrict \fIpath\fP,
- const posix_spawn_file_actions_t *\fIfile_actions\fP,
- const posix_spawnattr_t *restrict \fIattrp\fP,
- char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]);
- int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP,
- const posix_spawn_file_actions_t *\fIfile_actions\fP,
- const posix_spawnattr_t *restrict \fIattrp\fP,
- char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]);
- .fi
- .SH DESCRIPTION
- The
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- functions shall create a new process (child process) from the specified
- process image. The new process image shall be constructed from a regular
- executable file called the new process image file.
- .P
- When a C program is executed as the result of this call, it shall be
- entered as a C-language function call as follows:
- .sp
- .RS 4
- .nf
- int main(int \fIargc\fP, char *\fIargv\fP[]);
- .fi
- .P
- .RE
- .P
- where
- .IR argc
- is the argument count and
- .IR argv
- is an array of character pointers to the arguments themselves. In
- addition, the following variable:
- .sp
- .RS 4
- .nf
- extern char **environ;
- .fi
- .P
- .RE
- .P
- shall be initialized as a pointer to an array of character pointers to
- the environment strings.
- .P
- The argument
- .IR argv
- is an array of character pointers to null-terminated strings. The last
- member of this array shall be a null pointer and is not
- counted in
- .IR argc .
- These strings constitute the argument list available to the new process
- image. The value in
- .IR argv [0]
- should point to a filename string that is associated with the process
- image being started by the
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- function.
- .P
- The argument
- .IR envp
- is an array of character pointers to null-terminated strings. These
- strings constitute the environment for the new process image. The
- environment array is terminated by a null pointer.
- .P
- The number of bytes available for the combined argument
- and environment lists of the child process is
- {ARG_MAX}.
- The implementation shall specify in the system documentation (see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 2" ", " "Conformance")
- whether any list overhead, such as length words, null
- terminators, pointers, or alignment bytes, is included in this total.
- .P
- The
- .IR path
- argument to
- \fIposix_spawn\fR()
- is a pathname that identifies the new process image file to execute.
- .P
- The
- .IR file
- parameter to
- \fIposix_spawnp\fR()
- shall be used to construct a pathname that identifies the new process
- image file. If the
- .IR file
- parameter contains a
- <slash>
- character, the
- .IR file
- parameter shall be used as the pathname for the new process image
- file. Otherwise, the path prefix for this file shall be obtained by a
- search of the directories passed as the environment variable
- .IR PATH
- (see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables").
- If this environment variable is not defined, the results of the search
- are implementation-defined.
- .P
- If
- .IR file_actions
- is a null pointer, then file descriptors open in the calling process
- shall remain open in the child process, except for those whose
- close-on-\c
- .IR exec
- flag FD_CLOEXEC is set (see
- .IR "\fIfcntl\fR\^(\|)").
- For those file descriptors that remain open, the child process shall
- not inherit any file locks, but all remaining attributes of the
- corresponding open file descriptions (see
- .IR "\fIfcntl\fR\^(\|)"),
- shall remain unchanged.
- .P
- If
- .IR file_actions
- is not NULL, then the file descriptors open in the child process shall
- be those open in the calling process as modified by the spawn file
- actions object pointed to by
- .IR file_actions
- and the FD_CLOEXEC flag of each remaining open file descriptor after
- the spawn file actions have been processed. The effective order of
- processing the spawn file actions shall be:
- .IP " 1." 4
- The set of open file descriptors for the child process shall initially
- be the same set as is open for the calling process. The child process
- shall not inherit any file locks, but all remaining attributes of the
- corresponding open file descriptions (see
- .IR "\fIfcntl\fR\^(\|)"),
- shall remain unchanged.
- .IP " 2." 4
- The signal mask, signal default actions, and the effective user and
- group IDs for the child process shall be changed as specified in the
- attributes object referenced by
- .IR attrp .
- .IP " 3." 4
- The file actions specified by the spawn file actions object shall be
- performed in the order in which they were added to the spawn file
- actions object.
- .IP " 4." 4
- Any file descriptor that has its FD_CLOEXEC flag set (see
- .IR "\fIfcntl\fR\^(\|)")
- shall be closed.
- .P
- If file descriptor 0, 1, or 2 would otherwise be closed in the new
- process image created by
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR(),
- implementations may open an unspecified file for the file descriptor in
- the new process image. If a standard utility or a conforming application
- is executed with file descriptor 0 not open for reading or with file
- descriptor 1 or 2 not open for writing, the environment in which the
- utility or application is executed shall be deemed non-conforming, and
- consequently the utility or application might not behave as described
- in this standard.
- .P
- The
- .BR posix_spawnattr_t
- spawn attributes object type is defined in
- .IR <spawn.h> .
- It shall contain at least the attributes defined below.
- .P
- If the POSIX_SPAWN_SETPGROUP flag is set in the
- .IR spawn-flags
- attribute
- of the object referenced by
- .IR attrp ,
- and the
- .IR spawn-pgroup
- attribute of the same object is non-zero, then the child's process
- group shall be as specified in the
- .IR spawn-pgroup
- attribute of the object referenced by
- .IR attrp .
- .P
- As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- and the
- .IR spawn-pgroup
- attribute of the same object is set to zero, then the child shall be in
- a new process group with a process group ID equal to its process ID.
- .P
- If the POSIX_SPAWN_SETPGROUP flag is not set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- the new child process shall inherit the parent's process group.
- .P
- If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- but POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall
- initially have the scheduling policy of the calling process with the
- scheduling parameters specified in the
- .IR spawn-schedparam
- attribute of the object referenced by
- .IR attrp .
- .P
- If the POSIX_SPAWN_SETSCHEDULER flag is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp
- (regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), the
- new process image shall initially have the scheduling policy specified
- in the
- .IR spawn-schedpolicy
- attribute of the object referenced by
- .IR attrp
- and the scheduling parameters specified in the
- .IR spawn-schedparam
- attribute of the same object.
- .P
- The POSIX_SPAWN_RESETIDS flag in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp
- governs the effective user ID of the child process. If this flag is
- not set, the child process shall inherit the effective user ID of the
- parent process. If this flag is set, the effective user ID of the child
- process shall be reset to the parent's real user ID. In either case,
- if the set-user-ID mode bit of the new process image file is set, the
- effective user ID of the child process shall become that file's owner
- ID before the new process image begins execution.
- .P
- The POSIX_SPAWN_RESETIDS flag in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp
- also governs the effective group ID of the child process. If this flag
- is not set, the child process shall inherit the effective group ID of the
- parent process. If this flag is set, the effective group ID of the child
- process shall be reset to the parent's real group ID. In either case,
- if the set-group-ID mode bit of the new process image file is set, the
- effective group ID of the child process shall become that file's group
- ID before the new process image begins execution.
- .P
- If the POSIX_SPAWN_SETSIGMASK flag is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- the child process shall initially have the signal mask specified in the
- .IR spawn-sigmask
- attribute of the object referenced by
- .IR attrp .
- .P
- If the POSIX_SPAWN_SETSIGDEF flag is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- the signals specified in the
- .IR spawn-sigdefault
- attribute of the same object shall be set to their default actions in
- the child process. Signals set to the default action in the parent
- process shall be set to the default action in the child process.
- .P
- Signals set to be caught by the calling process shall be set to the
- default action in the child process.
- .P
- Except for SIGCHLD, signals set to be ignored by the calling process
- image shall be set to be ignored by the child process, unless otherwise
- specified by the POSIX_SPAWN_SETSIGDEF flag being set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp
- and the signals being indicated in the
- .IR spawn-sigdefault
- attribute of the object referenced by
- .IR attrp .
- .P
- If the SIGCHLD signal is set to be ignored by the calling process, it
- is unspecified whether the SIGCHLD signal is set to be ignored or to
- the default action in the child process, unless otherwise specified by
- the POSIX_SPAWN_SETSIGDEF flag being set in the
- .IR spawn_flags
- attribute of the object referenced by
- .IR attrp
- and the SIGCHLD signal being indicated in the
- .IR spawn_sigdefault
- attribute of the object referenced by
- .IR attrp .
- .P
- If the value of the
- .IR attrp
- pointer is NULL, then the default values are used.
- .P
- All process attributes, other than those influenced by the attributes
- set in the object referenced by
- .IR attrp
- as specified above or by the file descriptor manipulations specified in
- .IR file_actions ,
- shall appear in the new process image as though
- \fIfork\fR()
- had been called to create a child process and then a member of the
- .IR exec
- family of functions had been called by the child process to execute the
- new process image.
- .P
- It is implementation-defined whether the fork handlers are run when
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- is called.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- shall return the process ID of the child process to the parent process,
- in the variable pointed to by a non-NULL
- .IR pid
- argument, and shall return zero as the function return value.
- Otherwise, no child process shall be created, the value stored into the
- variable pointed to by a non-NULL
- .IR pid
- is unspecified, and an error number shall be returned as the function
- return value to indicate the error. If the
- .IR pid
- argument is a null pointer, the process ID of the child is not returned
- to the caller.
- .SH ERRORS
- These functions may fail if:
- .TP
- .BR EINVAL
- The value specified by
- .IR file_actions
- or
- .IR attrp
- is invalid.
- .P
- If this error occurs after the calling process successfully returns
- from the
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- function, the child process may exit with exit status 127.
- .P
- If
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- fail for any of the reasons that would cause
- \fIfork\fR()
- or one of the
- .IR exec
- family of functions to fail, an error value shall be returned as
- described by
- \fIfork\fR()
- and
- .IR exec ,
- respectively (or, if the error occurs after the calling process
- successfully returns, the child process shall exit with exit status 127).
- .P
- If POSIX_SPAWN_SETPGROUP is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- and
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- fails while changing the child's process group, an error value shall be
- returned as described by
- \fIsetpgid\fR()
- (or, if the error occurs after the calling process successfully
- returns, the child process shall exit with exit status 127).
- .P
- If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not
- set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- then if
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- fails for any of the reasons that would cause
- \fIsched_setparam\fR()
- to fail, an error value shall be returned as described by
- \fIsched_setparam\fR()
- (or, if the error occurs after the calling process successfully
- returns, the child process shall exit with exit status 127).
- .P
- If POSIX_SPAWN_SETSCHEDULER is set in the
- .IR spawn-flags
- attribute of the object referenced by
- .IR attrp ,
- and if
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- fails for any of the reasons that would cause
- \fIsched_setscheduler\fR()
- to fail, an error value shall be returned as described by
- \fIsched_setscheduler\fR()
- (or, if the error occurs after the calling process successfully
- returns, the child process shall exit with exit status 127).
- .P
- If the
- .IR file_actions
- argument is not NULL, and specifies any
- .IR close ,
- .IR dup2 ,
- or
- .IR open
- actions to be performed, and if
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- fails for any of the reasons that would cause
- \fIclose\fR(),
- \fIdup2\fR(),
- or
- \fIopen\fR()
- to fail, an error value shall be returned as described by
- \fIclose\fR(),
- \fIdup2\fR(),
- and
- \fIopen\fR(),
- respectively (or, if the error occurs after the calling process
- successfully returns, the child process shall exit with exit status
- 127). An open file action may, by itself, result in any of the errors
- described by
- \fIclose\fR()
- or
- \fIdup2\fR(),
- in addition to those described by
- \fIopen\fR().
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- These functions are part of the Spawn option and need not be
- provided on all implementations.
- .P
- See also the APPLICATION USAGE section for
- .IR "\fIexec\fR\^".
- .SH RATIONALE
- The
- \fIposix_spawn\fR()
- function and its close relation
- \fIposix_spawnp\fR()
- have been introduced to overcome the following perceived difficulties
- with
- \fIfork\fR():
- the
- \fIfork\fR()
- function is difficult or impossible to implement without swapping or
- dynamic address translation.
- .IP " *" 4
- Swapping is generally too slow for a realtime environment.
- .IP " *" 4
- Dynamic address translation is not available everywhere that POSIX
- might be useful.
- .IP " *" 4
- Processes are too useful to simply option out of POSIX whenever it must
- run without address translation or other MMU services.
- .P
- Thus, POSIX needs process creation and file execution primitives that
- can be efficiently implemented without address translation or other MMU
- services.
- .P
- The
- \fIposix_spawn\fR()
- function is implementable as a library routine, but both
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- are designed as kernel operations. Also, although they may be an
- efficient replacement for many
- \fIfork\fR()/\c
- .IR exec
- pairs, their goal is to provide useful process creation primitives for
- systems that have difficulty with
- \fIfork\fR(),
- not to provide drop-in replacements for
- \fIfork\fR()/\c
- .IR exec .
- .P
- This view of the role of
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- influenced the design of their API. It does not attempt to provide the
- full functionality of
- \fIfork\fR()/\c
- .IR exec
- in which arbitrary user-specified operations of any sort are permitted
- between the creation of the child process and the execution of the new
- process image; any attempt to reach that level would need to provide a
- programming language as parameters. Instead,
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- are process creation primitives like the
- .IR Start_Process
- and
- .IR Start_Process_Search
- Ada language bindings package
- .IR POSIX_Process_Primitives
- and also like those in many operating systems that are not UNIX
- systems, but with some POSIX-specific additions.
- .P
- To achieve its coverage goals,
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- have control of six types of inheritance: file descriptors, process
- group ID, user and group ID, signal mask, scheduling, and whether each
- signal ignored in the parent will remain ignored in the child, or be
- reset to its default action in the child.
- .P
- Control of file descriptors is required to allow an independently
- written child process image to access data streams opened by and even
- generated or read by the parent process without being specifically
- coded to know which parent files and file descriptors are to be used.
- Control of the process group ID is required to control how the
- job control of the child process relates to that of the parent.
- .P
- Control of the signal mask and signal defaulting is sufficient to
- support the implementation of
- \fIsystem\fR().
- Although support for
- \fIsystem\fR()
- is not explicitly one of the goals for
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR(),
- it is covered under the ``at least 50%'' coverage goal.
- .P
- The intention is that the normal file descriptor inheritance across
- \fIfork\fR(),
- the subsequent effect of the specified spawn file actions, and the
- normal file descriptor inheritance across one of the
- .IR exec
- family of functions should fully specify open file inheritance. The
- implementation need make no decisions regarding the set of open file
- descriptors when the child process image begins execution, those
- decisions having already been made by the caller and expressed as the
- set of open file descriptors and their FD_CLOEXEC flags at the time of
- the call and the spawn file actions object specified in the call. We
- have been assured that in cases where the POSIX
- .IR Start_Process
- Ada primitives have been implemented in a library, this method of
- controlling file descriptor inheritance may be implemented very easily.
- .P
- We can identify several problems with
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR(),
- but there does not appear to be a solution that introduces fewer
- problems. Environment modification for child process attributes not
- specifiable via the
- .IR attrp
- or
- .IR file_actions
- arguments must be done in the parent process, and since the parent
- generally wants to save its context, it is more costly than similar
- functionality with
- \fIfork\fR()/\c
- .IR exec .
- It is also complicated to modify the environment of a multi-threaded
- process temporarily, since all threads must agree when it is safe for
- the environment to be changed. However, this cost is only borne by
- those invocations of
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- that use the additional functionality. Since extensive modifications
- are not the usual case, and are particularly unlikely in time-critical
- code, keeping much of the environment control out of
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- is appropriate design.
- .P
- The
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- functions do not have all the power of
- \fIfork\fR()/\c
- .IR exec .
- This is to be expected. The
- \fIfork\fR()
- function is a wonderfully powerful operation. We do not expect to
- duplicate its functionality in a simple, fast function with no special
- hardware requirements. It is worth noting that
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- are very similar to the process creation operations on many operating
- systems that are not UNIX systems.
- .SS "Requirements"
- .P
- The requirements for
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- are:
- .IP " *" 4
- They must be implementable without an MMU or unusual hardware.
- .IP " *" 4
- They must be compatible with existing POSIX standards.
- .P
- Additional goals are:
- .IP " *" 4
- They should be efficiently implementable.
- .IP " *" 4
- They should be able to replace at least 50% of typical executions of
- \fIfork\fR().
- .IP " *" 4
- A system with
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- and without
- \fIfork\fR()
- should be useful, at least for realtime applications.
- .IP " *" 4
- A system with
- \fIfork\fR()
- and the
- .IR exec
- family should be able to implement
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- as library routines.
- .SS "Two-Syntax"
- .P
- POSIX
- .IR exec
- has several calling sequences with approximately the same
- functionality. These appear to be required for compatibility with
- existing practice. Since the existing practice for the
- .IR posix_spawn* (\|)
- functions is otherwise substantially unlike POSIX, we feel that
- simplicity outweighs compatibility. There are, therefore, only two
- names for the
- .IR posix_spawn* (\|)
- functions.
- .P
- The parameter list does not differ between
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR();
- \fIposix_spawnp\fR()
- interprets the second parameter more elaborately than
- \fIposix_spawn\fR().
- .SS "Compatibility with POSIX.5 (Ada)"
- .P
- The
- .IR Start_Process
- and
- .IR Start_Process_Search
- procedures from the
- .IR POSIX_Process_Primitives
- package from the Ada language binding to POSIX.1 encapsulate
- \fIfork\fR()
- and
- .IR exec
- functionality in a manner similar to that of
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR().
- Originally, in keeping with our simplicity goal, the standard
- developers had limited the capabilities of
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- to a subset of the capabilities of
- .IR Start_Process
- and
- .IR Start_Process_Search ;
- certain non-default capabilities were not supported. However, based on
- suggestions by the ballot group to improve file descriptor mapping or
- drop it, and on the advice of an Ada Language Bindings working group
- member, the standard developers decided that
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- should be sufficiently powerful to implement
- .IR Start_Process
- and
- .IR Start_Process_Search .
- The rationale is that if the Ada language binding to such a primitive
- had already been approved as an IEEE standard, there can be little
- justification for not approving the functionally-equivalent parts of a
- C binding. The only three capabilities provided by
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- that are not provided by
- .IR Start_Process
- and
- .IR Start_Process_Search
- are optionally specifying the child's process group ID, the set of
- signals to be reset to default signal handling in the child process,
- and the child's scheduling policy and parameters.
- .P
- For the Ada language binding for
- .IR Start_Process
- to be implemented with
- \fIposix_spawn\fR(),
- that binding would need to explicitly pass an empty signal mask and the
- parent's environment to
- \fIposix_spawn\fR()
- whenever the caller of
- .IR Start_Process
- allowed these arguments to default, since
- \fIposix_spawn\fR()
- does not provide such defaults. The ability of
- .IR Start_Process
- to mask user-specified signals during its execution is functionally
- unique to the Ada language binding and must be dealt with in the
- binding separately from the call to
- \fIposix_spawn\fR().
- .SS "Process Group"
- .P
- The process group inheritance field can be used to join the child
- process with an existing process group. By assigning a value of zero to
- the
- .IR spawn-pgroup
- attribute of the object referenced by
- .IR attrp ,
- the
- \fIsetpgid\fR()
- mechanism will place the child process in a new process group.
- .SS "Threads"
- .P
- Without the
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- functions, systems without address translation can still use threads to
- give an abstraction of concurrency. In many cases, thread creation
- suffices, but it is not always a good substitute. The
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- functions are considerably ``heavier'' than thread creation. Processes
- have several important attributes that threads do not. Even without
- address translation, a process may have base-and-bound memory
- protection. Each process has a process environment including security
- attributes and file capabilities, and powerful scheduling attributes.
- Processes abstract the behavior of non-uniform-memory-architecture
- multi-processors better than threads, and they are more convenient to
- use for activities that are not closely linked.
- .P
- The
- \fIposix_spawn\fR()
- and
- \fIposix_spawnp\fR()
- functions may not bring support for multiple processes to every
- configuration. Process creation is not the only piece of operating
- system support required to support multiple processes. The total cost
- of support for multiple processes may be quite high in some
- circumstances. Existing practice shows that support for multiple
- processes is uncommon and threads are common among ``tiny kernels''.
- There should, therefore, probably continue to be AEPs for operating
- systems with only one process.
- .SS "Asynchronous Error Notification"
- .P
- A library implementation of
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- may not be able to detect all possible errors before it forks the child
- process. POSIX.1\(hy2008 provides for an error indication returned from a child
- process which could not successfully complete the spawn operation via a
- special exit status which may be detected using the status value
- returned by
- \fIwait\fR(),
- \fIwaitid\fR(),
- and
- \fIwaitpid\fR().
- .P
- The
- .IR stat_val
- interface and the macros used to interpret it are not well suited to
- the purpose of returning API errors, but they are the only path
- available to a library implementation. Thus, an implementation may
- cause the child process to exit with exit status 127 for any error
- detected during the spawn process after the
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- function has successfully returned.
- .P
- The standard developers had proposed using two additional macros to
- interpret
- .IR stat_val .
- The first, WIFSPAWNFAIL, would have detected a status that indicated
- that the child exited because of an error detected during the
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- operations rather than during actual execution of the child process
- image; the second, WSPAWNERRNO, would have extracted the error value if
- WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group
- strongly opposed this because it would make a library implementation of
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- dependent on kernel modifications to
- \fIwaitpid\fR()
- to be able to embed special information in
- .IR stat_val
- to indicate a spawn failure.
- .P
- The 8 bits of child process exit status that are guaranteed by POSIX.1\(hy2008 to
- be accessible to the waiting parent process are insufficient to
- disambiguate a spawn error from any other kind of error that may be
- returned by an arbitrary process image. No other bits of the exit
- status are required to be visible in
- .IR stat_val ,
- so these macros could not be strictly implemented at the library level.
- Reserving an exit status of 127 for such spawn errors is consistent
- with the use of this value by
- \fIsystem\fR()
- and
- \fIpopen\fR()
- to signal failures in these operations that occur after the function
- has returned but before a shell is able to execute. The exit status of
- 127 does not uniquely identify this class of error, nor does it provide
- any detailed information on the nature of the failure. Note that a
- kernel implementation of
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- is permitted (and encouraged) to return any possible error as the
- function value, thus providing more detailed failure information to the
- parent process.
- .P
- Thus, no special macros are available to isolate asynchronous
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- errors. Instead, errors detected by the
- \fIposix_spawn\fR()
- or
- \fIposix_spawnp\fR()
- operations in the context of the child process before the new process
- image executes are reported by setting the child's exit status to 127.
- The calling process may use the WIFEXITED and WEXITSTATUS macros on the
- .IR stat_val
- stored by the
- \fIwait\fR()
- or
- \fIwaitpid\fR()
- functions to detect spawn failures to the extent that other status
- values with which the child process image may exit (before the parent
- can conclusively determine that the child process image has begun
- execution) are distinct from exit status 127.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .ad l
- .IR "\fIalarm\fR\^(\|)",
- .IR "\fIchmod\fR\^(\|)",
- .IR "\fIclose\fR\^(\|)",
- .IR "\fIdup\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIexit\fR\^(\|)",
- .IR "\fIfcntl\fR\^(\|)",
- .IR "\fIfork\fR\^(\|)",
- .IR "\fIfstatat\fR\^(\|)",
- .IR "\fIkill\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)",
- .IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)",
- .IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)",
- .IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)",
- .IR "\fIposix_spawnattr_destroy\fR\^(\|)",
- .IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)",
- .IR "\fIposix_spawnattr_getflags\fR\^(\|)",
- .IR "\fIposix_spawnattr_getpgroup\fR\^(\|)",
- .IR "\fIposix_spawnattr_getschedparam\fR\^(\|)",
- .IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)",
- .IR "\fIposix_spawnattr_getsigmask\fR\^(\|)",
- .IR "\fIsched_setparam\fR\^(\|)",
- .IR "\fIsched_setscheduler\fR\^(\|)",
- .IR "\fIsetpgid\fR\^(\|)",
- .IR "\fIsetuid\fR\^(\|)",
- .IR "\fItimes\fR\^(\|)",
- .IR "\fIwait\fR\^(\|)",
- .IR "\fIwaitid\fR\^(\|)"
- .ad b
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "\fB<spawn.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .