]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
bf5a7247 | 2 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
7f26d075 | 3 | .\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
c08df37a | 6 | .\" |
fea681da MK |
7 | .\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu) |
8 | .\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) | |
9 | .\" Modified 14 May 2001, 23 Sep 2001 by aeb | |
dc23fde1 | 10 | .\" 2004-12-20, mtk |
fea681da | 11 | .\" |
4c1c5274 | 12 | .TH system 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
13 | .SH NAME |
14 | system \- execute a shell command | |
c6bd2457 AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <stdlib.h> | |
c6d039a3 | 21 | .P |
dc23fde1 | 22 | .BI "int system(const char *" "command" ); |
fea681da MK |
23 | .fi |
24 | .SH DESCRIPTION | |
7f26d075 | 25 | The |
dc23fde1 | 26 | .BR system () |
f1153690 | 27 | library function behaves as if it used |
7f26d075 | 28 | .BR fork (2) |
f1153690 | 29 | to create a child process that executed the shell command specified in |
dc23fde1 | 30 | .I command |
7f26d075 MK |
31 | using |
32 | .BR execl (3) | |
33 | as follows: | |
c6d039a3 | 34 | .P |
4f5bbd61 MK |
35 | .in +4n |
36 | .EX | |
86d93b3e | 37 | execl("/bin/sh", "sh", "\-c", command, (char *) NULL); |
4f5bbd61 MK |
38 | .EE |
39 | .in | |
c6d039a3 | 40 | .P |
7f26d075 MK |
41 | .BR system () |
42 | returns after the command has been completed. | |
c6d039a3 | 43 | .P |
fea681da MK |
44 | During execution of the command, |
45 | .B SIGCHLD | |
46 | will be blocked, and | |
47 | .B SIGINT | |
48 | and | |
49 | .B SIGQUIT | |
7f26d075 | 50 | will be ignored, in the process that calls |
f80fdeaf MK |
51 | .BR system (). |
52 | (These signals will be handled according to their defaults inside | |
7f26d075 | 53 | the child process that executes |
f80fdeaf | 54 | .IR command .) |
c6d039a3 | 55 | .P |
7f26d075 | 56 | If |
dc23fde1 | 57 | .I command |
7f26d075 | 58 | is NULL, then |
dc23fde1 | 59 | .BR system () |
e4631a35 | 60 | returns a status indicating whether a shell is available on the system. |
7f26d075 MK |
61 | .SH RETURN VALUE |
62 | The return value of | |
63 | .BR system () | |
64 | is one of the following: | |
cdede5cd | 65 | .IP \[bu] 3 |
7f26d075 MK |
66 | If |
67 | .I command | |
68 | is NULL, then a nonzero value if a shell is available, | |
69 | or 0 if no shell is available. | |
cdede5cd | 70 | .IP \[bu] |
7f26d075 MK |
71 | If a child process could not be created, |
72 | or its status could not be retrieved, | |
0cb0dd1c MK |
73 | the return value is \-1 and |
74 | .I errno | |
75 | is set to indicate the error. | |
cdede5cd | 76 | .IP \[bu] |
7f26d075 MK |
77 | If a shell could not be executed in the child process, |
78 | then the return value is as though the child shell terminated by calling | |
79 | .BR _exit (2) | |
80 | with the status 127. | |
cdede5cd | 81 | .IP \[bu] |
7f26d075 MK |
82 | If all system calls succeed, |
83 | then the return value is the termination status of the child shell | |
84 | used to execute | |
85 | .IR command . | |
86 | (The termination status of a shell is the termination status of | |
87 | the last command it executes.) | |
c6d039a3 | 88 | .P |
7f26d075 MK |
89 | In the last two cases, |
90 | the return value is a "wait status" that can be examined using | |
91 | the macros described in | |
92 | .BR waitpid (2). | |
93 | (i.e., | |
00e295fb MK |
94 | .BR WIFEXITED (), |
95 | .BR WEXITSTATUS (), | |
7f26d075 | 96 | and so on). |
c6d039a3 | 97 | .P |
dc23fde1 | 98 | .BR system () |
fea681da | 99 | does not affect the wait status of any other children. |
63e59e0d MK |
100 | .SH ERRORS |
101 | .BR system () | |
102 | can fail with any of the same errors as | |
103 | .BR fork (2). | |
527c8d41 | 104 | .SH ATTRIBUTES |
130567d4 PH |
105 | For an explanation of the terms used in this section, see |
106 | .BR attributes (7). | |
107 | .TS | |
108 | allbox; | |
c466875e | 109 | lbx lb lb |
130567d4 PH |
110 | l l l. |
111 | Interface Attribute Value | |
112 | T{ | |
9e54434e BR |
113 | .na |
114 | .nh | |
527c8d41 | 115 | .BR system () |
130567d4 PH |
116 | T} Thread safety MT-Safe |
117 | .TE | |
3113c7f3 | 118 | .SH STANDARDS |
4131356c AC |
119 | C11, POSIX.1-2008. |
120 | .SH HISTORY | |
121 | POSIX.1-2001, C89. | |
fea681da | 122 | .SH NOTES |
7f26d075 MK |
123 | .BR system () |
124 | provides simplicity and convenience: | |
125 | it handles all of the details of calling | |
126 | .BR fork (2), | |
127 | .BR execl (3), | |
128 | and | |
129 | .BR waitpid (2), | |
130 | as well as the necessary manipulations of signals; | |
131 | in addition, | |
132 | the shell performs the usual substitutions and I/O redirections for | |
133 | .IR command . | |
134 | The main cost of | |
135 | .BR system () | |
136 | is inefficiency: | |
137 | additional system calls are required to create the process that | |
138 | runs the shell and to execute the shell. | |
c6d039a3 | 139 | .P |
dc23fde1 MK |
140 | If the |
141 | .B _XOPEN_SOURCE | |
e417acb0 MK |
142 | feature test macro is defined |
143 | (before including | |
144 | .I any | |
145 | header files), | |
146 | then the macros described in | |
7f26d075 | 147 | .BR waitpid (2) |
f87925c6 | 148 | .RB ( WEXITSTATUS (), |
dc23fde1 | 149 | etc.) are made available when including |
c13182ef | 150 | .IR <stdlib.h> . |
c6d039a3 | 151 | .P |
fea681da | 152 | As mentioned, |
dc23fde1 | 153 | .BR system () |
8bd58774 MK |
154 | ignores |
155 | .B SIGINT | |
156 | and | |
157 | .BR SIGQUIT . | |
1c44bd5b | 158 | This may make programs that call it |
b9560046 | 159 | from a loop uninterruptible, unless they take care themselves |
c13182ef | 160 | to check the exit status of the child. |
7f26d075 | 161 | For example: |
c6d039a3 | 162 | .P |
a2b7a144 MK |
163 | .in +4n |
164 | .EX | |
165 | while (something) { | |
166 | int ret = system("foo"); | |
fe5dba13 | 167 | \& |
a2b7a144 MK |
168 | if (WIFSIGNALED(ret) && |
169 | (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) | |
170 | break; | |
171 | } | |
172 | .EE | |
173 | .in | |
c6d039a3 | 174 | .P |
26cfa7d3 MK |
175 | According to POSIX.1, it is unspecified whether handlers registered using |
176 | .BR pthread_atfork (3) | |
177 | are called during the execution of | |
178 | .BR system (). | |
179 | In the glibc implementation, such handlers are not called. | |
c6d039a3 | 180 | .P |
b324e17d | 181 | Before glibc 2.1.3, the check for the availability of |
dc23fde1 MK |
182 | .I /bin/sh |
183 | was not actually performed if | |
184 | .I command | |
185 | was NULL; instead it was always assumed to be available, and | |
186 | .BR system () | |
187 | always returned 1 in this case. | |
188 | Since glibc 2.1.3, this check is performed because, even though | |
189 | POSIX.1-2001 requires a conforming implementation to provide | |
190 | a shell, that shell may not be available or executable if | |
191 | the calling program has previously called | |
192 | .BR chroot (2) | |
193 | (which is not specified by POSIX.1-2001). | |
c6d039a3 | 194 | .P |
7f26d075 MK |
195 | It is possible for the shell command to terminate with a status of 127, |
196 | which yields a | |
197 | .BR system () | |
198 | return value that is indistinguishable from the case | |
199 | where a shell could not be executed in the child process. | |
a6be81ba MK |
200 | .\" |
201 | .SS Caveats | |
a6be81ba MK |
202 | Do not use |
203 | .BR system () | |
2e039d4d MK |
204 | from a privileged program |
205 | (a set-user-ID or set-group-ID program, or a program with capabilities) | |
a6be81ba MK |
206 | because strange values for some environment variables |
207 | might be used to subvert system integrity. | |
3b9f2b67 | 208 | For example, |
1ae6b2c7 | 209 | .B PATH |
3b9f2b67 MK |
210 | could be manipulated so that an arbitrary program |
211 | is executed with privilege. | |
a6be81ba MK |
212 | Use the |
213 | .BR exec (3) | |
214 | family of functions instead, but not | |
215 | .BR execlp (3) | |
216 | or | |
3b9f2b67 MK |
217 | .BR execvp (3) |
218 | (which also use the | |
219 | .B PATH | |
220 | environment variable to search for an executable). | |
c6d039a3 | 221 | .P |
a6be81ba MK |
222 | .BR system () |
223 | will not, in fact, work properly from programs with set-user-ID or | |
224 | set-group-ID privileges on systems on which | |
225 | .I /bin/sh | |
1f87e639 | 226 | is bash version 2: as a security measure, bash 2 drops privileges on startup. |
bd64aa64 MK |
227 | (Debian uses a different shell, |
228 | .BR dash (1), | |
229 | which does not do this when invoked as | |
a6be81ba | 230 | .BR sh .) |
c6d039a3 | 231 | .P |
067f8064 MK |
232 | Any user input that is employed as part of |
233 | .I command | |
234 | should be | |
235 | .I carefully | |
236 | sanitized, to ensure that unexpected shell commands or command options | |
237 | are not executed. | |
238 | Such risks are especially grave when using | |
239 | .BR system () | |
240 | from a privileged program. | |
47973831 AC |
241 | .SH BUGS |
242 | .\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029) | |
75c018a1 | 243 | .\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143) |
47973831 AC |
244 | .\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440) |
245 | If the command name starts with a hyphen, | |
246 | .BR sh (1) | |
247 | interprets the command name as an option, | |
248 | and the behavior is undefined. | |
249 | (See the | |
250 | .B \-c | |
251 | option to | |
252 | .BR sh (1).) | |
253 | To work around this problem, | |
254 | prepend the command with a space as in the following call: | |
c6d039a3 | 255 | .P |
91c6bf1c | 256 | .in +4n |
47973831 AC |
257 | .EX |
258 | system(" \-unfortunate\-command\-name"); | |
259 | .EE | |
91c6bf1c | 260 | .in |
47297adb | 261 | .SH SEE ALSO |
fea681da | 262 | .BR sh (1), |
fb7a9afd | 263 | .BR execve (2), |
c0f12d15 | 264 | .BR fork (2), |
7f26d075 MK |
265 | .BR sigaction (2), |
266 | .BR sigprocmask (2), | |
fea681da | 267 | .BR wait (2), |
7f26d075 MK |
268 | .BR exec (3), |
269 | .BR signal (7) |