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