system.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>There are three levels of specification for the <i>system</i>() function. The ISO&nbsp;C standard gives the most basic. It
requires that the function exists, and defines a way for an application to query whether a command language interpreter exists. It
says nothing about the command language or the environment in which the command is interpreted.</p>

<p>IEEE&nbsp;Std&nbsp;1003.1-2001 places additional restrictions on <i>system</i>(). It requires that if there is a command
language interpreter, the environment must be as specified by <a href="../functions/fork.html"><i>fork</i>()</a> and <i><a href=
"../functions/exec.html">exec</a></i>. This ensures, for example, that close-on- <i><a href="../functions/exec.html">exec</a></i>
works, that file locks are not inherited, and that the process ID is different. It also specifies the return value from
<i>system</i>() when the command line can be run, thus giving the application some information about the command's completion
status.</p>

<p>Finally, IEEE&nbsp;Std&nbsp;1003.1-2001 requires the command to be interpreted as in the shell command language defined in the
Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>Note that, <i>system</i>(NULL) is required to return non-zero, indicating that there is a command language interpreter. At first
glance, this would seem to conflict with the ISO&nbsp;C standard which allows <i>system</i>(NULL) to return zero. There is no
conflict, however. A system must have a command language interpreter, and is non-conforming if none is present. It is therefore
permissible for the <i>system</i>() function on such a system to implement the behavior specified by the ISO&nbsp;C standard as
long as it is understood that the implementation does not conform to IEEE&nbsp;Std&nbsp;1003.1-2001 if <i>system</i>(NULL) returns
zero.</p>

<p>It was explicitly decided that when <i>command</i> is NULL, <i>system</i>() should not be required to check to make sure that
the command language interpreter actually exists with the correct mode, that there are enough processes to execute it, and so on.
The call <i>system</i>(NULL) could, theoretically, check for such problems as too many existing child processes, and return zero.
However, it would be inappropriate to return zero due to such a (presumably) transient condition. If some condition exists that is
not under the control of this application and that would cause any <i>system</i>() call to fail, that system has been rendered
non-conforming.</p>

<p>Early drafts required, or allowed, <i>system</i>() to return with <i>errno</i> set to [EINTR] if it was interrupted with a
signal. This error return was removed, and a requirement that <i>system</i>() not return until the child has terminated was added.
This means that if a <a href="../functions/waitpid.html"><i>waitpid</i>()</a> call in <i>system</i>() exits with <i>errno</i> set
to [EINTR], <i>system</i>() must reissue the <a href="../functions/waitpid.html"><i>waitpid</i>()</a>. This change was made for two
reasons:</p>

<ol>
<li>
<p>There is no way for an application to clean up if <i>system</i>() returns [EINTR], short of calling <a href=
"../functions/wait.html"><i>wait</i>()</a>, and that could have the undesirable effect of returning the status of children other
than the one started by <i>system</i>().</p>
</li>

<li>
<p>While it might require a change in some historical implementations, those implementations already have to be changed because
they use <a href="../functions/wait.html"><i>wait</i>()</a> instead of <a href=
"../functions/waitpid.html"><i>waitpid</i>()</a>.</p>
</li>
</ol>

<p>Note that if the application is catching SIGCHLD signals, it will receive such a signal before a successful <i>system</i>() call
returns.</p>

<p>To conform to IEEE&nbsp;Std&nbsp;1003.1-2001, <i>system</i>() must use <a href="../functions/waitpid.html"><i>waitpid</i>()</a>,
or some similar function, instead of <a href="../functions/wait.html"><i>wait</i>()</a>.</p>

<p>The following code sample illustrates how <i>system</i>() might be implemented on an implementation conforming to
IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<pre>
<tt>#include &lt;signal.h&gt;
int system(const char *cmd)
{
    int stat;
    pid_t pid;
    struct sigaction sa, savintr, savequit;
    sigset_t saveblock;
    if (cmd == NULL)
        return(1);
    sa.sa_handler = SIG_IGN;
    sigemptyset(&amp;sa.sa_mask);
    sa.sa_flags = 0;
    sigemptyset(&amp;savintr.sa_mask);
    sigemptyset(&amp;savequit.sa_mask);
    sigaction(SIGINT, &amp;sa, &amp;savintr);
    sigaction(SIGQUIT, &amp;sa, &amp;savequit);
    sigaddset(&amp;sa.sa_mask, SIGCHLD);
    sigprocmask(SIG_BLOCK, &amp;sa.sa_mask, &amp;saveblock);
    if ((pid = fork()) == 0) {
        sigaction(SIGINT, &amp;savintr, (struct sigaction *)0);
        sigaction(SIGQUIT, &amp;savequit, (struct sigaction *)0);
        sigprocmask(SIG_SETMASK, &amp;saveblock, (sigset_t *)0);
        execl("/bin/sh", "sh", "-c", cmd, (char *)0);
        _exit(127);
    }
    if (pid == -1) {
        stat = -1; /* errno comes from fork() */
    } else {
        while (waitpid(pid, &amp;stat, 0) == -1) {
            if (errno != EINTR){
                stat = -1;
                break;
            }
        }
    }
    sigaction(SIGINT, &amp;savintr, (struct sigaction *)0);
    sigaction(SIGQUIT, &amp;savequit, (struct sigaction *)0);
    sigprocmask(SIG_SETMASK, &amp;saveblock, (sigset_t *)0);
    return(stat);
}
</tt>
</pre>

<p>Note that, while a particular implementation of <i>system</i>() (such as the one above) can assume a particular path for the
shell, such a path is not necessarily valid on another system. The above example is not portable, and is not intended to be.</p>

<p>One reviewer suggested that an implementation of <i>system</i>() might want to use an environment variable such as <i>SHELL</i>
to determine which command interpreter to use. The supposed implementation would use the default command interpreter if the one
specified by the environment variable was not available. This would allow a user, when using an application that prompts for
command lines to be processed using <i>system</i>(), to specify a different command interpreter. Such an implementation is
discouraged. If the alternate command interpreter did not follow the command line syntax specified in the Shell and Utilities
volume of IEEE&nbsp;Std&nbsp;1003.1-2001, then changing <i>SHELL</i> would render <i>system</i>() non-conforming. This would affect
applications that expected the specified behavior from <i>system</i>(), and since the Shell and Utilities volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 does not mention that <i>SHELL</i> affects <i>system</i>(), the application would not know that it
needed to unset <i>SHELL .</i></p>
</blockquote>

<h4><a name="tag_03_757_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_757_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="pipe.html"><i>pipe</i>()</a> , <a href=
"waitpid.html"><i>waitpid</i>()</a> , the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a>, <a href="../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a>, <a href=
"../basedefs/stdlib.h.html"><i>&lt;stdlib.h&gt;</i></a>, <a href="../basedefs/sys/wait.h.html"><i>&lt;sys/wait.h&gt;</i></a>, the
Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../utilities/sh.html"><i>sh</i></a></p>
</blockquote>

<h4><a name="tag_03_757_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
</blockquote>

<h4><a name="tag_03_757_12"></a>Issue 6</h4>

<blockquote>
<p>Extensions beyond the ISO&nbsp;C standard are marked.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>