320 lines
18 KiB
HTML
320 lines
18 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>system</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="system"></a> <a name="tag_03_757"></a><!-- system -->
|
|
<!--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_757_01"></a>NAME</h4>
|
|
|
|
<blockquote>system - issue a command</blockquote>
|
|
|
|
<h4><a name="tag_03_757_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/stdlib.h.html">stdlib.h</a>><br>
|
|
<br>
|
|
int system(const char *</tt><i>command</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_757_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the
|
|
requirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers to
|
|
the ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
|
|
|
|
<p>If <i>command</i> is a null pointer, the <i>system</i>() function shall determine whether the host environment has a command
|
|
processor. If <i>command</i> is not a null pointer, the <i>system</i>() function shall pass the string pointed to by <i>command</i>
|
|
to that command processor to be executed in an implementation-defined manner; this might then cause the program calling
|
|
<i>system</i>() to behave in a non-conforming manner or to terminate.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The
|
|
environment of the executed command shall be as if a child process were created using <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>, and the child process invoked the <a href="../utilities/sh.html"><i>sh</i></a> utility
|
|
using <a href="../functions/execl.html"><i>execl</i>()</a> as follows:</p>
|
|
|
|
<pre>
|
|
<tt>execl(<</tt><i>shell path</i><tt>>, "sh", "-c",</tt> <i>command</i><tt>, (char *)0);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>where <<i>shell path</i>> is an unspecified pathname for the <a href="../utilities/sh.html"><i>sh</i></a> utility.</p>
|
|
|
|
<p>The <i>system</i>() function shall ignore the SIGINT and SIGQUIT signals, and shall block the SIGCHLD signal, while waiting for
|
|
the command to terminate. If this might cause the application to miss a signal that would have killed it, then the application
|
|
should examine the return value from <i>system</i>() and take whatever action is appropriate to the application if the command
|
|
terminated due to receipt of a signal.</p>
|
|
|
|
<p>The <i>system</i>() function shall not affect the termination status of any child of the calling processes other than the
|
|
process or processes it itself creates.</p>
|
|
|
|
<p>The <i>system</i>() function shall not return until the child process has terminated. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_757_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If <i>command</i> is a null pointer, <i>system</i>() shall return non-zero to indicate that a command processor is available, or
|
|
zero if none is available. <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> The <i>system</i>() function shall always return non-zero when <i>command</i> is NULL. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If
|
|
<i>command</i> is not a null pointer, <i>system</i>() shall return the termination status of the command language interpreter in
|
|
the format specified by <a href="../functions/waitpid.html"><i>waitpid</i>()</a>. The termination status shall be as defined for
|
|
the <a href="../utilities/sh.html"><i>sh</i></a> utility; otherwise, the termination status is unspecified. If some error prevents
|
|
the command language interpreter from executing after the child process is created, the return value from <i>system</i>() shall be
|
|
as if the command language interpreter had terminated using <i>exit</i>(127) or <i>_exit</i>(127). If a child process cannot be
|
|
created, or if the termination status for the command language interpreter cannot be obtained, <i>system</i>() shall return -1 and
|
|
set <i>errno</i> to indicate the error. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_757_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The
|
|
<i>system</i>() function may set <i>errno</i> values as described by <a href="fork.html"><i>fork</i>()</a> . <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>In addition, <i>system</i>() may fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[ECHILD]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The status of the child process created by <i>system</i>() is no longer available. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_757_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_757_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the return value of <i>system</i>() is not -1, its value can be decoded through the use of the macros described in <a href=
|
|
"../basedefs/sys/wait.h.html"><i><sys/wait.h></i></a>. For convenience, these macros are also provided in <a href=
|
|
"../basedefs/stdlib.h.html"><i><stdlib.h></i></a>.</p>
|
|
|
|
<p>Note that, while <i>system</i>() must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting for the child to terminate, the
|
|
handling of signals in the executed command is as specified by <a href="../functions/fork.html"><i>fork</i>()</a> and <i><a href=
|
|
"../functions/exec.html">exec</a></i>. For example, if SIGINT is being caught or is set to SIG_DFL when <i>system</i>() is called,
|
|
then the child is started with SIGINT handling set to SIG_DFL.</p>
|
|
|
|
<p>Ignoring SIGINT and SIGQUIT in the parent process prevents coordination problems (two processes reading from the same terminal,
|
|
for example) when the executed command ignores or catches one of the signals. It is also usually the correct action when the user
|
|
has given a command to the application to be executed synchronously (as in the <tt>'!'</tt> command in many interactive
|
|
applications). In either case, the signal should be delivered only to the child process, not to the application itself. There is
|
|
one situation where ignoring the signals might have less than the desired effect. This is when the application uses <i>system</i>()
|
|
to perform some task invisible to the user. If the user typed the interrupt character ( <tt>"^C"</tt> , for example) while
|
|
<i>system</i>() is being used in this way, one would expect the application to be killed, but only the executed command is killed.
|
|
Applications that use <i>system</i>() in this way should carefully check the return status from <i>system</i>() to see if the
|
|
executed command was successful, and should take appropriate action when the command fails.</p>
|
|
|
|
<p>Blocking SIGCHLD while waiting for the child to terminate prevents the application from catching the signal and obtaining status
|
|
from <i>system</i>()'s child process before <i>system</i>() can get the status itself.</p>
|
|
|
|
<p>The context in which the utility is ultimately executed may differ from that in which <i>system</i>() was called. For example,
|
|
file descriptors that have the FD_CLOEXEC flag set are closed, and the process ID and parent process ID are different. Also, if the
|
|
executed utility changes its environment variables or its current working directory, that change is not reflected in the caller's
|
|
context.</p>
|
|
|
|
<p>There is no defined way for an application to find the specific path for the shell. However, <a href=
|
|
"../functions/confstr.html"><i>confstr</i>()</a> can provide a value for <i>PATH</i> that is guaranteed to find the <a href=
|
|
"../utilities/sh.html"><i>sh</i></a> utility.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_757_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>system</i>() function should not be used by programs that have set user (or group) ID privileges. The <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> and <i><a href="../functions/exec.html">exec</a></i> family of functions (except <a
|
|
href="../functions/execlp.html"><i>execlp</i>()</a> and <a href="../functions/execvp.html"><i>execvp</i>()</a>), should be used
|
|
instead. This prevents any unforeseen manipulation of the environment of the user that could cause execution of commands not
|
|
anticipated by the calling program.</p>
|
|
|
|
<p>There are three levels of specification for the <i>system</i>() function. The ISO 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 Std 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 Std 1003.1-2001 requires the command to be interpreted as in the shell command language defined in the
|
|
Shell and Utilities volume of IEEE Std 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 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 C standard as
|
|
long as it is understood that the implementation does not conform to IEEE Std 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 Std 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 Std 1003.1-2001.</p>
|
|
|
|
<pre>
|
|
<tt>#include <signal.h>
|
|
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(&sa.sa_mask);
|
|
sa.sa_flags = 0;
|
|
sigemptyset(&savintr.sa_mask);
|
|
sigemptyset(&savequit.sa_mask);
|
|
sigaction(SIGINT, &sa, &savintr);
|
|
sigaction(SIGQUIT, &sa, &savequit);
|
|
sigaddset(&sa.sa_mask, SIGCHLD);
|
|
sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock);
|
|
if ((pid = fork()) == 0) {
|
|
sigaction(SIGINT, &savintr, (struct sigaction *)0);
|
|
sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
|
|
sigprocmask(SIG_SETMASK, &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, &stat, 0) == -1) {
|
|
if (errno != EINTR){
|
|
stat = -1;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
sigaction(SIGINT, &savintr, (struct sigaction *)0);
|
|
sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
|
|
sigprocmask(SIG_SETMASK, &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 Std 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 Std 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 Std 1003.1-2001, <a href=
|
|
"../basedefs/limits.h.html"><i><limits.h></i></a>, <a href="../basedefs/signal.h.html"><i><signal.h></i></a>, <a href=
|
|
"../basedefs/stdlib.h.html"><i><stdlib.h></i></a>, <a href="../basedefs/sys/wait.h.html"><i><sys/wait.h></i></a>, the
|
|
Shell and Utilities volume of IEEE Std 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 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 ® 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>
|
|
|