Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 936 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/posix_spawn.3p b/upstream/archlinux/man3p/posix_spawn.3p
new file mode 100644
index 00000000..876fa9d1
--- /dev/null
+++ b/upstream/archlinux/man3p/posix_spawn.3p
@@ -0,0 +1,936 @@
+'\" 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 .