1SYSTEM(3P) POSIX Programmer's Manual SYSTEM(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 system - issue a command
13
15 #include <stdlib.h>
16 int system(const char *command);
18
21 If command is a null pointer, the system() function shall determine
22 whether the host environment has a command processor. If command is not
23 a null pointer, the system() function shall pass the string pointed to
24 by command to that command processor to be executed in an implementa‐
25 tion-defined manner; this might then cause the program calling system()
26 to behave in a non-conforming manner or to terminate.
27 The environment of the executed command shall be as if a child process
29 were created using fork(), and the child process invoked the sh utility
30 using execl() as follows:
31 execl(<shell path>, "sh", "-c", command, (char *)0);
34 where <shell path> is an unspecified pathname for the sh utility.
36 The system() function shall ignore the SIGINT and SIGQUIT signals, and
38 shall block the SIGCHLD signal, while waiting for the command to termi‐
39 nate. If this might cause the application to miss a signal that would
40 have killed it, then the application should examine the return value
41 from system() and take whatever action is appropriate to the applica‐
42 tion if the command terminated due to receipt of a signal.
43 The system() function shall not affect the termination status of any
45 child of the calling processes other than the process or processes it
46 itself creates.
47 The system() function shall not return until the child process has ter‐
49 minated.
50
52 If command is a null pointer, system() shall return non-zero to indi‐
53 cate that a command processor is available, or zero if none is avail‐
54 able. The system() function shall always return non-zero when command
55 is NULL.
56 If command is not a null pointer, system() shall return the termination
58 status of the command language interpreter in the format specified by
59 waitpid(). The termination status shall be as defined for the sh util‐
60 ity; otherwise, the termination status is unspecified. If some error
61 prevents the command language interpreter from executing after the
62 child process is created, the return value from system() shall be as if
63 the command language interpreter had terminated using exit(127) or
64 _exit(127). If a child process cannot be created, or if the termination
65 status for the command language interpreter cannot be obtained, sys‐
66 tem() shall return -1 and set errno to indicate the error.
67
69 The system() function may set errno values as described by fork().
70 In addition, system() may fail if:
72 ECHILD The status of the child process created by system() is no longer
74 available.
75 The following sections are informative.
78
80 None.
81
83 If the return value of system() is not -1, its value can be decoded
84 through the use of the macros described in <sys/wait.h>. For conve‐
85 nience, these macros are also provided in <stdlib.h>.
86 Note that, while system() must ignore SIGINT and SIGQUIT and block
88 SIGCHLD while waiting for the child to terminate, the handling of sig‐
89 nals in the executed command is as specified by fork() and exec. For
90 example, if SIGINT is being caught or is set to SIG_DFL when system()
91 is called, then the child is started with SIGINT handling set to
92 SIG_DFL.
93 Ignoring SIGINT and SIGQUIT in the parent process prevents coordination
95 problems (two processes reading from the same terminal, for example)
96 when the executed command ignores or catches one of the signals. It is
97 also usually the correct action when the user has given a command to
98 the application to be executed synchronously (as in the '!' command in
99 many interactive applications). In either case, the signal should be
100 delivered only to the child process, not to the application itself.
101 There is one situation where ignoring the signals might have less than
102 the desired effect. This is when the application uses system() to per‐
103 form some task invisible to the user. If the user typed the interrupt
104 character ( "^C", for example) while system() is being used in this
105 way, one would expect the application to be killed, but only the exe‐
106 cuted command is killed. Applications that use system() in this way
107 should carefully check the return status from system() to see if the
108 executed command was successful, and should take appropriate action
109 when the command fails.
110 Blocking SIGCHLD while waiting for the child to terminate prevents the
112 application from catching the signal and obtaining status from sys‐
113 tem()'s child process before system() can get the status itself.
114 The context in which the utility is ultimately executed may differ from
116 that in which system() was called. For example, file descriptors that
117 have the FD_CLOEXEC flag set are closed, and the process ID and parent
118 process ID are different. Also, if the executed utility changes its
119 environment variables or its current working directory, that change is
120 not reflected in the caller's context.
121 There is no defined way for an application to find the specific path
123 for the shell. However, confstr() can provide a value for PATH that is
124 guaranteed to find the sh utility.
125
127 The system() function should not be used by programs that have set user
128 (or group) ID privileges. The fork() and exec family of functions
129 (except execlp() and execvp()), should be used instead. This prevents
130 any unforeseen manipulation of the environment of the user that could
131 cause execution of commands not anticipated by the calling program.
132 There are three levels of specification for the system() function. The
134 ISO C standard gives the most basic. It requires that the function
135 exists, and defines a way for an application to query whether a command
136 language interpreter exists. It says nothing about the command language
137 or the environment in which the command is interpreted.
138 IEEE Std 1003.1-2001 places additional restrictions on system(). It
140 requires that if there is a command language interpreter, the environ‐
141 ment must be as specified by fork() and exec. This ensures, for exam‐
142 ple, that close-on- exec works, that file locks are not inherited, and
143 that the process ID is different. It also specifies the return value
144 from system() when the command line can be run, thus giving the appli‐
145 cation some information about the command's completion status.
146 Finally, IEEE Std 1003.1-2001 requires the command to be interpreted as
148 in the shell command language defined in the Shell and Utilities volume
149 of IEEE Std 1003.1-2001.
150 Note that, system(NULL) is required to return non-zero, indicating that
152 there is a command language interpreter. At first glance, this would
153 seem to conflict with the ISO C standard which allows system(NULL) to
154 return zero. There is no conflict, however. A system must have a com‐
155 mand language interpreter, and is non-conforming if none is present. It
156 is therefore permissible for the system() function on such a system to
157 implement the behavior specified by the ISO C standard as long as it is
158 understood that the implementation does not conform to
159 IEEE Std 1003.1-2001 if system(NULL) returns zero.
160 It was explicitly decided that when command is NULL, system() should
162 not be required to check to make sure that the command language inter‐
163 preter actually exists with the correct mode, that there are enough
164 processes to execute it, and so on. The call system(NULL) could, theo‐
165 retically, check for such problems as too many existing child pro‐
166 cesses, and return zero. However, it would be inappropriate to return
167 zero due to such a (presumably) transient condition. If some condition
168 exists that is not under the control of this application and that would
169 cause any system() call to fail, that system has been rendered non-con‐
170 forming.
171 Early drafts required, or allowed, system() to return with errno set to
173 [EINTR] if it was interrupted with a signal. This error return was
174 removed, and a requirement that system() not return until the child has
175 terminated was added. This means that if a waitpid() call in system()
176 exits with errno set to [EINTR], system() must reissue the waitpid().
177 This change was made for two reasons:
178 1. There is no way for an application to clean up if system() returns
180 [EINTR], short of calling wait(), and that could have the undesir‐
181 able effect of returning the status of children other than the one
182 started by system().
183 2. While it might require a change in some historical implementations,
185 those implementations already have to be changed because they use
186 wait() instead of waitpid().
187 Note that if the application is catching SIGCHLD signals, it will
189 receive such a signal before a successful system() call returns.
190 To conform to IEEE Std 1003.1-2001, system() must use waitpid(), or
192 some similar function, instead of wait().
193 The following code sample illustrates how system() might be implemented
195 on an implementation conforming to IEEE Std 1003.1-2001.
196 #include <signal.h>
199 int system(const char *cmd)
200 {
201 int stat;
202 pid_t pid;
203 struct sigaction sa, savintr, savequit;
204 sigset_t saveblock;
205 if (cmd == NULL)
206 return(1);
207 sa.sa_handler = SIG_IGN;
208 sigemptyset(&sa.sa_mask);
209 sa.sa_flags = 0;
210 sigemptyset(&savintr.sa_mask);
211 sigemptyset(&savequit.sa_mask);
212 sigaction(SIGINT, &sa, &savintr);
213 sigaction(SIGQUIT, &sa, &savequit);
214 sigaddset(&sa.sa_mask, SIGCHLD);
215 sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock);
216 if ((pid = fork()) == 0) {
217 sigaction(SIGINT, &savintr, (struct sigaction *)0);
218 sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
219 sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0);
220 execl("/bin/sh", "sh", "-c", cmd, (char *)0);
221 _exit(127);
222 }
223 if (pid == -1) {
224 stat = -1; /* errno comes from fork() */
225 } else {
226 while (waitpid(pid, &stat, 0) == -1) {
227 if (errno != EINTR){
228 stat = -1;
229 break;
230 }
231 }
232 }
233 sigaction(SIGINT, &savintr, (struct sigaction *)0);
234 sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
235 sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0);
236 return(stat);
237 }
238 Note that, while a particular implementation of system() (such as the
240 one above) can assume a particular path for the shell, such a path is
241 not necessarily valid on another system. The above example is not por‐
242 table, and is not intended to be.
243 One reviewer suggested that an implementation of system() might want to
245 use an environment variable such as SHELL to determine which command
246 interpreter to use. The supposed implementation would use the default
247 command interpreter if the one specified by the environment variable
248 was not available. This would allow a user, when using an application
249 that prompts for command lines to be processed using system(), to spec‐
250 ify a different command interpreter. Such an implementation is discour‐
251 aged. If the alternate command interpreter did not follow the command
252 line syntax specified in the Shell and Utilities volume of
253 IEEE Std 1003.1-2001, then changing SHELL would render system() non-
254 conforming. This would affect applications that expected the specified
255 behavior from system(), and since the Shell and Utilities volume of
256 IEEE Std 1003.1-2001 does not mention that SHELL affects system(), the
257 application would not know that it needed to unset SHELL.
258
260 None.
261
263 exec(), pipe(), waitpid(), the Base Definitions volume of
264 IEEE Std 1003.1-2001, <limits.h>, <signal.h>, <stdlib.h>, <sys/wait.h>,
265 the Shell and Utilities volume of IEEE Std 1003.1-2001, sh
266
268 Portions of this text are reprinted and reproduced in electronic form
269 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
270 -- Portable Operating System Interface (POSIX), The Open Group Base
271 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
272 Electrical and Electronics Engineers, Inc and The Open Group. In the
273 event of any discrepancy between this version and the original IEEE and
274 The Open Group Standard, the original IEEE and The Open Group Standard
275 is the referee document. The original Standard can be obtained online
276 at http://www.opengroup.org/unix/online.html .
277IEEE/The Open Group 2003 SYSTEM(3P)