541 lines
36 KiB
HTML
541 lines
36 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>posix_spawn</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="posix_spawn"></a> <a name="tag_03_427"></a><!-- posix_spawn -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_427_01"></a>NAME</h4>
|
|
|
|
<blockquote>posix_spawn, posix_spawnp - spawn a process (<b>ADVANCED REALTIME</b>)</blockquote>
|
|
|
|
<h4><a name="tag_03_427_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('SPN')">SPN</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/spawn.h.html">spawn.h</a>><br>
|
|
<br>
|
|
int posix_spawn(pid_t *restrict</tt> <i>pid</i><tt>, const char *restrict</tt> <i>path</i><tt>,<br>
|
|
const posix_spawn_file_actions_t *</tt><i>file_actions</i><tt>,<br>
|
|
const posix_spawnattr_t *restrict</tt> <i>attrp</i><tt>,<br>
|
|
char *const</tt> <i>argv</i><tt>[restrict], char *const</tt> <i>envp</i><tt>[restrict]);<br>
|
|
int posix_spawnp(pid_t *restrict</tt> <i>pid</i><tt>, const char *restrict</tt> <i>file</i><tt>,<br>
|
|
const posix_spawn_file_actions_t *</tt><i>file_actions</i><tt>,<br>
|
|
const posix_spawnattr_t *restrict</tt> <i>attrp</i><tt>,<br>
|
|
char *const</tt> <i>argv</i><tt>[restrict], char * const</tt> <i>envp</i><tt>[restrict]);
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_427_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>posix_spawn</i>() and <i>posix_spawnp</i>() 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>
|
|
|
|
<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:</p>
|
|
|
|
<pre>
|
|
<tt>int main(int</tt> <i>argc</i><tt>, char *</tt><i>argv</i><tt>[]);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where <i>argc</i> is the argument count and <i>argv</i> is an array of character pointers to the arguments themselves. In
|
|
addition, the following variable:</p>
|
|
|
|
<pre>
|
|
<tt>extern char **environ;
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>shall be initialized as a pointer to an array of character pointers to the environment strings.</p>
|
|
|
|
<p>The argument <i>argv</i> 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 <i>argc</i>. These strings constitute the argument list available to the new process image. The
|
|
value in <i>argv</i>[0] should point to a filename that is associated with the process image being started by the
|
|
<i>posix_spawn</i>() or <i>posix_spawnp</i>() function.</p>
|
|
|
|
<p>The argument <i>envp</i> 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>
|
|
|
|
<p>The number of bytes available for the child process' combined argument and environment lists is {ARG_MAX}. The implementation
|
|
shall specify in the system documentation (see the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap02.html#tag_02">Chapter 2, Conformance</a>) whether any list overhead, such as length words, null terminators,
|
|
pointers, or alignment bytes, is included in this total.</p>
|
|
|
|
<p>The <i>path</i> argument to <i>posix_spawn</i>() is a pathname that identifies the new process image file to execute.</p>
|
|
|
|
<p>The <i>file</i> parameter to <i>posix_spawnp</i>() shall be used to construct a pathname that identifies the new process image
|
|
file. If the <i>file</i> parameter contains a slash character, the <i>file</i> 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 <i>PATH</i> (see the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap08.html">Chapter 8, Environment Variables</a>). If this environment variable is not defined, the results of
|
|
the search are implementation-defined.</p>
|
|
|
|
<p>If <i>file_actions</i> 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- <i><a href="../functions/exec.html">exec</a></i> flag FD_CLOEXEC is set (see <a href=
|
|
"fcntl.html"><i>fcntl</i>()</a> ). For those file descriptors that remain open, all attributes of the corresponding open file
|
|
descriptions, including file locks (see <a href="fcntl.html"><i>fcntl</i>()</a> ), shall remain unchanged.</p>
|
|
|
|
<p>If <i>file_actions</i> 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 <i>file_actions</i> 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:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The set of open file descriptors for the child process shall initially be the same set as is open for the calling process. All
|
|
attributes of the corresponding open file descriptions, including file locks (see <a href="fcntl.html"><i>fcntl</i>()</a> ), shall
|
|
remain unchanged.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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 <i>attrp</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Any file descriptor that has its FD_CLOEXEC flag set (see <a href="fcntl.html"><i>fcntl</i>()</a> ) shall be closed.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>The <b>posix_spawnattr_t</b> spawn attributes object type is defined in <a href=
|
|
"../basedefs/spawn.h.html"><i><spawn.h></i></a>. It shall contain at least the attributes defined below.</p>
|
|
|
|
<p>If the POSIX_SPAWN_SETPGROUP flag is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, and the
|
|
<i>spawn-pgroup</i> attribute of the same object is non-zero, then the child's process group shall be as specified in the
|
|
<i>spawn-pgroup</i> attribute of the object referenced by <i>attrp</i>.</p>
|
|
|
|
<p>As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the <i>spawn-flags</i> attribute of the object referenced by
|
|
<i>attrp</i>, and the <i>spawn-pgroup</i> 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>
|
|
|
|
<p>If the POSIX_SPAWN_SETPGROUP flag is not set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, the
|
|
new child process shall inherit the parent's process group.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('PS')">PS</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If
|
|
the POSIX_SPAWN_SETSCHEDPARAM flag is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, 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 <i>spawn-schedparam</i> attribute of the object referenced by <i>attrp</i>.</p>
|
|
|
|
<p>If the POSIX_SPAWN_SETSCHEDULER flag is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>
|
|
(regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), the new process image shall initially have the scheduling policy
|
|
specified in the <i>spawn-schedpolicy</i> attribute of the object referenced by <i>attrp</i> and the scheduling parameters
|
|
specified in the <i>spawn-schedparam</i> attribute of the same object. <img src="../images/opt-end.gif" alt="[Option End]" border=
|
|
"0"></p>
|
|
|
|
<p>The POSIX_SPAWN_RESETIDS flag in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i> governs the effective
|
|
user ID of the child process. If this flag is not set, the child process shall inherit the parent process' effective user ID. If
|
|
this flag is set, the child process' effective user ID 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>
|
|
|
|
<p>The POSIX_SPAWN_RESETIDS flag in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i> also governs the
|
|
effective group ID of the child process. If this flag is not set, the child process shall inherit the parent process' effective
|
|
group ID. If this flag is set, the child process' effective group ID 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>
|
|
|
|
<p>If the POSIX_SPAWN_SETSIGMASK flag is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, the
|
|
child process shall initially have the signal mask specified in the <i>spawn-sigmask</i> attribute of the object referenced by
|
|
<i>attrp</i>.</p>
|
|
|
|
<p>If the POSIX_SPAWN_SETSIGDEF flag is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, the
|
|
signals specified in the <i>spawn-sigdefault</i> 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>
|
|
|
|
<p>Signals set to be caught by the calling process shall be set to the default action in the child process.</p>
|
|
|
|
<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 <i>spawn-flags</i> attribute of the object referenced
|
|
by <i>attrp</i> and the signals being indicated in the <i>spawn-sigdefault</i> attribute of the object referenced by
|
|
<i>attrp</i>.</p>
|
|
|
|
<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 <i>spawn_flags</i> attribute of the object referenced by <i>attrp</i> and the SIGCHLD signal being indicated in the
|
|
<i>spawn_sigdefault</i> attribute of the object referenced by <i>attrp</i>.</p>
|
|
|
|
<p>If the value of the <i>attrp</i> pointer is NULL, then the default values are used.</p>
|
|
|
|
<p>All process attributes, other than those influenced by the attributes set in the object referenced by <i>attrp</i> as specified
|
|
above or by the file descriptor manipulations specified in <i>file_actions</i>, shall appear in the new process image as though <a
|
|
href="../functions/fork.html"><i>fork</i>()</a> had been called to create a child process and then a member of the <i><a href=
|
|
"../functions/exec.html">exec</a></i> family of functions had been called by the child process to execute the new process
|
|
image.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('THR')">THR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
It is implementation-defined whether the fork handlers are run when <i>posix_spawn</i>() or <i>posix_spawnp</i>() is called. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>posix_spawn</i>() and <i>posix_spawnp</i>() shall return the process ID of the child process to
|
|
the parent process, in the variable pointed to by a non-NULL <i>pid</i> 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 <i>pid</i> is
|
|
unspecified, and an error number shall be returned as the function return value to indicate the error. If the <i>pid</i> argument
|
|
is a null pointer, the process ID of the child is not returned to the caller.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>posix_spawn</i>() and <i>posix_spawnp</i>() functions may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value specified by <i>file_actions</i> or <i>attrp</i> is invalid.</dd>
|
|
</dl>
|
|
|
|
<p>If this error occurs after the calling process successfully returns from the <i>posix_spawn</i>() or <i>posix_spawnp</i>()
|
|
function, the child process may exit with exit status 127.</p>
|
|
|
|
<p>If <i>posix_spawn</i>() or <i>posix_spawnp</i>() fail for any of the reasons that would cause <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> or one of the <i><a href="../functions/exec.html">exec</a></i> family of functions to
|
|
fail, an error value shall be returned as described by <a href="../functions/fork.html"><i>fork</i>()</a> and <i><a href=
|
|
"../functions/exec.html">exec</a></i>, respectively (or, if the error occurs after the calling process successfully returns, the
|
|
child process shall exit with exit status 127).</p>
|
|
|
|
<p>If POSIX_SPAWN_SETPGROUP is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, and
|
|
<i>posix_spawn</i>() or <i>posix_spawnp</i>() fails while changing the child's process group, an error value shall be returned as
|
|
described by <a href="../functions/setpgid.html"><i>setpgid</i>()</a> (or, if the error occurs after the calling process
|
|
successfully returns, the child process shall exit with exit status 127).</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('PS')">PS</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If
|
|
POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not set in the <i>spawn-flags</i> attribute of the object
|
|
referenced by <i>attrp</i>, then if <i>posix_spawn</i>() or <i>posix_spawnp</i>() fails for any of the reasons that would cause <a
|
|
href="../functions/sched_setparam.html"><i>sched_setparam</i>()</a> to fail, an error value shall be returned as described by <a
|
|
href="../functions/sched_setparam.html"><i>sched_setparam</i>()</a> (or, if the error occurs after the calling process successfully
|
|
returns, the child process shall exit with exit status 127).</p>
|
|
|
|
<p>If POSIX_SPAWN_SETSCHEDULER is set in the <i>spawn-flags</i> attribute of the object referenced by <i>attrp</i>, and if
|
|
<i>posix_spawn</i>() or <i>posix_spawnp</i>() fails for any of the reasons that would cause <a href=
|
|
"../functions/sched_setscheduler.html"><i>sched_setscheduler</i>()</a> to fail, an error value shall be returned as described by <a
|
|
href="../functions/sched_setscheduler.html"><i>sched_setscheduler</i>()</a> (or, if the error occurs after the calling process
|
|
successfully returns, the child process shall exit with exit status 127). <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></p>
|
|
|
|
<p>If the <i>file_actions</i> argument is not NULL, and specifies any <i>close</i>, <i>dup2</i>, or <i>open</i> actions to be
|
|
performed, and if <i>posix_spawn</i>() or <i>posix_spawnp</i>() fails for any of the reasons that would cause <a href=
|
|
"../functions/close.html"><i>close</i>()</a>, <a href="../functions/dup2.html"><i>dup2</i>()</a>, or <a href=
|
|
"../functions/open.html"><i>open</i>()</a> to fail, an error value shall be returned as described by <a href=
|
|
"../functions/close.html"><i>close</i>()</a>, <a href="../functions/dup2.html"><i>dup2</i>()</a>, and <a href=
|
|
"../functions/open.html"><i>open</i>()</a>, 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 <a
|
|
href="../functions/close.html"><i>close</i>()</a> or <a href="../functions/dup2.html"><i>dup2</i>()</a>, in addition to those
|
|
described by <a href="../functions/open.html"><i>open</i>()</a>.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_427_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>These functions are part of the Spawn option and need not be provided on all implementations.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>posix_spawn</i>() function and its close relation <i>posix_spawnp</i>() have been introduced to overcome the following
|
|
perceived difficulties with <a href="../functions/fork.html"><i>fork</i>()</a>: the <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> function is difficult or impossible to implement without swapping or dynamic address
|
|
translation.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Swapping is generally too slow for a realtime environment.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Dynamic address translation is not available everywhere that POSIX might be useful.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Processes are too useful to simply option out of POSIX whenever it must run without address translation or other MMU
|
|
services.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Thus, POSIX needs process creation and file execution primitives that can be efficiently implemented without address translation
|
|
or other MMU services.</p>
|
|
|
|
<p>The <i>posix_spawn</i>() function is implementable as a library routine, but both <i>posix_spawn</i>() and <i>posix_spawnp</i>()
|
|
are designed as kernel operations. Also, although they may be an efficient replacement for many <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>/ <i><a href="../functions/exec.html">exec</a></i> pairs, their goal is to provide useful
|
|
process creation primitives for systems that have difficulty with <a href="../functions/fork.html"><i>fork</i>()</a>, not to
|
|
provide drop-in replacements for <a href="../functions/fork.html"><i>fork</i>()</a>/ <i><a href=
|
|
"../functions/exec.html">exec</a></i>.</p>
|
|
|
|
<p>This view of the role of <i>posix_spawn</i>() and <i>posix_spawnp</i>() influenced the design of their API. It does not attempt
|
|
to provide the full functionality of <a href="../functions/fork.html"><i>fork</i>()</a>/ <i><a href=
|
|
"../functions/exec.html">exec</a></i> 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, <i>posix_spawn</i>() and <i>posix_spawnp</i>() are process creation primitives like
|
|
the <i>Start_Process</i> and <i>Start_Process_Search</i> Ada language bindings package <i>POSIX_Process_Primitives</i> and also
|
|
like those in many operating systems that are not UNIX systems, but with some POSIX-specific additions.</p>
|
|
|
|
<p>To achieve its coverage goals, <i>posix_spawn</i>() and <i>posix_spawnp</i>() 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>
|
|
|
|
<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 child process' job control relates to that of the
|
|
parent.</p>
|
|
|
|
<p>Control of the signal mask and signal defaulting is sufficient to support the implementation of <a href=
|
|
"../functions/system.html"><i>system</i>()</a>. Although support for <a href="../functions/system.html"><i>system</i>()</a> is not
|
|
explicitly one of the goals for <i>posix_spawn</i>() and <i>posix_spawnp</i>(), it is covered under the "at least 50%" coverage
|
|
goal.</p>
|
|
|
|
<p>The intention is that the normal file descriptor inheritance across <a href="../functions/fork.html"><i>fork</i>()</a>, the
|
|
subsequent effect of the specified spawn file actions, and the normal file descriptor inheritance across one of the <i><a href=
|
|
"../functions/exec.html">exec</a></i> 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
|
|
<i>Start_Process</i> Ada primitives have been implemented in a library, this method of controlling file descriptor inheritance may
|
|
be implemented very easily.</p>
|
|
|
|
<p>We can identify several problems with <i>posix_spawn</i>() and <i>posix_spawnp</i>(), but there does not appear to be a solution
|
|
that introduces fewer problems. Environment modification for child process attributes not specifiable via the <i>attrp</i> or
|
|
<i>file_actions</i> 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 <a href="../functions/fork.html"><i>fork</i>()</a>/ <i><a href=
|
|
"../functions/exec.html">exec</a></i>. 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 <i>posix_spawn</i>() and <i>posix_spawnp</i>() 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
|
|
<i>posix_spawn</i>() and <i>posix_spawnp</i>() is appropriate design.</p>
|
|
|
|
<p>The <i>posix_spawn</i>() and <i>posix_spawnp</i>() functions do not have all the power of <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>/ <i><a href="../functions/exec.html">exec</a></i>. This is to be expected. The <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> 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 <i>posix_spawn</i>() and
|
|
<i>posix_spawnp</i>() are very similar to the process creation operations on many operating systems that are not UNIX systems.</p>
|
|
|
|
<h5><a name="tag_03_427_08_01"></a>Requirements</h5>
|
|
|
|
<p>The requirements for <i>posix_spawn</i>() and <i>posix_spawnp</i>() are:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>They must be implementable without an MMU or unusual hardware.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>They must be compatible with existing POSIX standards.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Additional goals are:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>They should be efficiently implementable.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>They should be able to replace at least 50% of typical executions of <a href="../functions/fork.html"><i>fork</i>()</a>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A system with <i>posix_spawn</i>() and <i>posix_spawnp</i>() and without <a href="../functions/fork.html"><i>fork</i>()</a>
|
|
should be useful, at least for realtime applications.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A system with <a href="../functions/fork.html"><i>fork</i>()</a> and the <i><a href="../functions/exec.html">exec</a></i> family
|
|
should be able to implement <i>posix_spawn</i>() and <i>posix_spawnp</i>() as library routines.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h5><a name="tag_03_427_08_02"></a>Two-Syntax</h5>
|
|
|
|
<p>POSIX <i><a href="../functions/exec.html">exec</a></i> 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 <a href=
|
|
"../functions/posix_spawn.html"><i>posix_spawn*</i>()</a> functions is otherwise substantially unlike POSIX, we feel that
|
|
simplicity outweighs compatibility. There are, therefore, only two names for the <a href=
|
|
"../functions/posix_spawn.html"><i>posix_spawn*</i>()</a> functions.</p>
|
|
|
|
<p>The parameter list does not differ between <i>posix_spawn</i>() and <i>posix_spawnp</i>(); <i>posix_spawnp</i>() interprets the
|
|
second parameter more elaborately than <i>posix_spawn</i>().</p>
|
|
|
|
<h5><a name="tag_03_427_08_03"></a>Compatibility with POSIX.5 (Ada)</h5>
|
|
|
|
<p>The <i>Start_Process</i> and <i>Start_Process_Search</i> procedures from the <i>POSIX_Process_Primitives</i> package from the
|
|
Ada language binding to POSIX.1 encapsulate <a href="../functions/fork.html"><i>fork</i>()</a> and <i><a href=
|
|
"../functions/exec.html">exec</a></i> functionality in a manner similar to that of <i>posix_spawn</i>() and <i>posix_spawnp</i>().
|
|
Originally, in keeping with our simplicity goal, the standard developers had limited the capabilities of <i>posix_spawn</i>() and
|
|
<i>posix_spawnp</i>() to a subset of the capabilities of <i>Start_Process</i> and <i>Start_Process_Search</i>; 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 <i>posix_spawn</i>() and
|
|
<i>posix_spawnp</i>() should be sufficiently powerful to implement <i>Start_Process</i> and <i>Start_Process_Search</i>. 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
|
|
<i>posix_spawn</i>() and <i>posix_spawnp</i>() that are not provided by <i>Start_Process</i> and <i>Start_Process_Search</i> 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>
|
|
|
|
<p>For the Ada language binding for <i>Start_Process</i> to be implemented with <i>posix_spawn</i>(), that binding would need to
|
|
explicitly pass an empty signal mask and the parent's environment to <i>posix_spawn</i>() whenever the caller of
|
|
<i>Start_Process</i> allowed these arguments to default, since <i>posix_spawn</i>() does not provide such defaults. The ability of
|
|
<i>Start_Process</i> 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 <i>posix_spawn</i>().</p>
|
|
|
|
<h5><a name="tag_03_427_08_04"></a>Process Group</h5>
|
|
|
|
<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 <i>spawn-pgroup</i> attribute of the object referenced by <i>attrp</i>, the <a href=
|
|
"../functions/setpgid.html"><i>setpgid</i>()</a> mechanism will place the child process in a new process group.</p>
|
|
|
|
<h5><a name="tag_03_427_08_05"></a>Threads</h5>
|
|
|
|
<p>Without the <i>posix_spawn</i>() and <i>posix_spawnp</i>() 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
|
|
<i>posix_spawn</i>() and <i>posix_spawnp</i>() 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>
|
|
|
|
<p>The <i>posix_spawn</i>() and <i>posix_spawnp</i>() 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.</p>
|
|
|
|
<h5><a name="tag_03_427_08_06"></a>Asynchronous Error Notification</h5>
|
|
|
|
<p>A library implementation of <i>posix_spawn</i>() or <i>posix_spawnp</i>() may not be able to detect all possible errors before
|
|
it forks the child process. IEEE Std 1003.1-2001 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 <a href="../functions/wait.html"><i>wait</i>()</a> and <a href="../functions/waitpid.html"><i>waitpid</i>()</a>.</p>
|
|
|
|
<p>The <i>stat_val</i> 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 <i>posix_spawn</i>() or <i>posix_spawnp</i>() function
|
|
has successfully returned.</p>
|
|
|
|
<p>The standard developers had proposed using two additional macros to interpret <i>stat_val</i>. The first, WIFSPAWNFAIL, would
|
|
have detected a status that indicated that the child exited because of an error detected during the <i>posix_spawn</i>() or
|
|
<i>posix_spawnp</i>() 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 <i>posix_spawn</i>() or <i>posix_spawnp</i>() dependent on kernel modifications to <a
|
|
href="../functions/waitpid.html"><i>waitpid</i>()</a> to be able to embed special information in <i>stat_val</i> to indicate a
|
|
spawn failure.</p>
|
|
|
|
<p>The 8 bits of child process exit status that are guaranteed by IEEE Std 1003.1-2001 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 <i>stat_val</i>, 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 <a href="../functions/system.html"><i>system</i>()</a> and <a href="../functions/popen.html"><i>popen</i>()</a> 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 <i>posix_spawn</i>() or <i>posix_spawnp</i>() is permitted (and encouraged) to return any possible
|
|
error as the function value, thus providing more detailed failure information to the parent process.</p>
|
|
|
|
<p>Thus, no special macros are available to isolate asynchronous <i>posix_spawn</i>() or <i>posix_spawnp</i>() errors. Instead,
|
|
errors detected by the <i>posix_spawn</i>() or <i>posix_spawnp</i>() 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 <i>stat_val</i> stored by the <a href="../functions/wait.html"><i>wait</i>()</a> or <a href=
|
|
"../functions/waitpid.html"><i>waitpid</i>()</a> 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.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="alarm.html"><i>alarm</i>()</a> , <a href="chmod.html"><i>chmod</i>()</a> , <a href="close.html"><i>close</i>()</a> , <a
|
|
href="dup.html"><i>dup</i>()</a> , <a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href=
|
|
"exit.html"><i>exit</i>()</a> , <a href="fcntl.html"><i>fcntl</i>()</a> , <a href="fork.html"><i>fork</i>()</a> , <a href=
|
|
"kill.html"><i>kill</i>()</a> , <a href="open.html"><i>open</i>()</a> , <a href=
|
|
"posix_spawn_file_actions_addclose.html"><i>posix_spawn_file_actions_addclose</i>()</a> , <a href=
|
|
"posix_spawn_file_actions_adddup2.html"><i>posix_spawn_file_actions_adddup2</i>()</a> , <a href=
|
|
"posix_spawn_file_actions_addopen.html"><i>posix_spawn_file_actions_addopen</i>()</a> , <a href=
|
|
"posix_spawn_file_actions_destroy.html"><i>posix_spawn_file_actions_destroy</i>()</a> , , <a href=
|
|
"posix_spawnattr_destroy.html"><i>posix_spawnattr_destroy</i>()</a> , <a href=
|
|
"posix_spawnattr_init.html"><i>posix_spawnattr_init</i>()</a> , <a href=
|
|
"posix_spawnattr_getsigdefault.html"><i>posix_spawnattr_getsigdefault</i>()</a> , <a href=
|
|
"posix_spawnattr_getflags.html"><i>posix_spawnattr_getflags</i>()</a> , <a href=
|
|
"posix_spawnattr_getpgroup.html"><i>posix_spawnattr_getpgroup</i>()</a> , <a href=
|
|
"posix_spawnattr_getschedparam.html"><i>posix_spawnattr_getschedparam</i>()</a> , <a href=
|
|
"posix_spawnattr_getschedpolicy.html"><i>posix_spawnattr_getschedpolicy</i>()</a> , <a href=
|
|
"posix_spawnattr_getsigmask.html"><i>posix_spawnattr_getsigmask</i>()</a> , <a href=
|
|
"posix_spawnattr_setsigdefault.html"><i>posix_spawnattr_setsigdefault</i>()</a> , <a href=
|
|
"posix_spawnattr_setflags.html"><i>posix_spawnattr_setflags</i>()</a> , <a href=
|
|
"posix_spawnattr_setpgroup.html"><i>posix_spawnattr_setpgroup</i>()</a> , <a href=
|
|
"posix_spawnattr_setschedparam.html"><i>posix_spawnattr_setschedparam</i>()</a> , <a href=
|
|
"posix_spawnattr_setschedpolicy.html"><i>posix_spawnattr_setschedpolicy</i>()</a> , <a href=
|
|
"posix_spawnattr_setsigmask.html"><i>posix_spawnattr_setsigmask</i>()</a> , <a href=
|
|
"sched_setparam.html"><i>sched_setparam</i>()</a> , <a href="sched_setscheduler.html"><i>sched_setscheduler</i>()</a> , <a href=
|
|
"setpgid.html"><i>setpgid</i>()</a> , <a href="setuid.html"><i>setuid</i>()</a> , <a href="stat.html"><i>stat</i>()</a> , <a href=
|
|
"times.html"><i>times</i>()</a> , <a href="wait.html"><i>wait</i>()</a> , the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/spawn.h.html"><i><spawn.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_427_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Derived from IEEE Std 1003.1d-1999.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.1 #103 is applied, noting that the signal default actions are changed as well as the signal mask
|
|
in step 2.</p>
|
|
|
|
<p>IEEE PASC Interpretation 1003.1 #132 is applied.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|