Debian Codegraph @

upstream/debian-unstable/man3/system.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright 2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH system 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 system \- execute a shell command
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BI "int system(const char *" "command" );
19 .fi
20 .SH DESCRIPTION
21 The
22 .BR system ()
23 library function behaves as if it used
24 .BR fork (2)
25 to create a child process that executed the shell command specified in
26 .I command
27 using
28 .BR execl (3)
29 as follows:
30 .P
31 .in +4n
32 .EX
33 execl("/bin/sh", "sh", "\-c", command, (char *) NULL);
34 .EE
35 .in
36 .P
37 .BR system ()
38 returns after the command has been completed.
39 .P
40 During execution of the command,
41 .B SIGCHLD
42 will be blocked, and
43 .B SIGINT
44 and
45 .B SIGQUIT
46 will be ignored, in the process that calls
47 .BR system ().
48 (These signals will be handled according to their defaults inside
49 the child process that executes
50 .IR command .)
51 .P
52 If
53 .I command
54 is NULL, then
55 .BR system ()
56 returns a status indicating whether a shell is available on the system.
57 .SH RETURN VALUE
58 The return value of
59 .BR system ()
60 is one of the following:
61 .IP \[bu] 3
62 If
63 .I command
64 is NULL, then a nonzero value if a shell is available,
65 or 0 if no shell is available.
66 .IP \[bu]
67 If a child process could not be created,
68 or its status could not be retrieved,
69 the return value is \-1 and
70 .I errno
71 is set to indicate the error.
72 .IP \[bu]
73 If a shell could not be executed in the child process,
74 then the return value is as though the child shell terminated by calling
75 .BR _exit (2)
76 with the status 127.
77 .IP \[bu]
78 If all system calls succeed,
79 then the return value is the termination status of the child shell
80 used to execute
81 .IR command .
82 (The termination status of a shell is the termination status of
83 the last command it executes.)
84 .P
85 In the last two cases,
86 the return value is a "wait status" that can be examined using
87 the macros described in
88 .BR waitpid (2).
89 (i.e.,
90 .BR WIFEXITED (),
91 .BR WEXITSTATUS (),
92 and so on).
93 .P
94 .BR system ()
95 does not affect the wait status of any other children.
96 .SH ERRORS
97 .BR system ()
98 can fail with any of the same errors as
99 .BR fork (2).
100 .SH ATTRIBUTES
101 For an explanation of the terms used in this section, see
102 .BR attributes (7).
103 .TS
104 allbox;
105 lbx lb lb
106 l l l.
107 Interface Attribute Value
108 T{
109 .na
110 .nh
111 .BR system ()
112 T} Thread safety MT-Safe
113 .TE
114 .SH STANDARDS
115 C11, POSIX.1-2008.
116 .SH HISTORY
117 POSIX.1-2001, C89.
118 .SH NOTES
119 .BR system ()
120 provides simplicity and convenience:
121 it handles all of the details of calling
122 .BR fork (2),
123 .BR execl (3),
124 and
125 .BR waitpid (2),
126 as well as the necessary manipulations of signals;
127 in addition,
128 the shell performs the usual substitutions and I/O redirections for
129 .IR command .
130 The main cost of
131 .BR system ()
132 is inefficiency:
133 additional system calls are required to create the process that
134 runs the shell and to execute the shell.
135 .P
136 If the
137 .B _XOPEN_SOURCE
138 feature test macro is defined
139 (before including
140 .I any
141 header files),
142 then the macros described in
143 .BR waitpid (2)
144 .RB ( WEXITSTATUS (),
145 etc.) are made available when including
146 .IR <stdlib.h> .
147 .P
148 As mentioned,
149 .BR system ()
150 ignores
151 .B SIGINT
152 and
153 .BR SIGQUIT .
154 This may make programs that call it
155 from a loop uninterruptible, unless they take care themselves
156 to check the exit status of the child.
157 For example:
158 .P
159 .in +4n
160 .EX
161 while (something) {
162 int ret = system("foo");
163 \&
164 if (WIFSIGNALED(ret) &&
165 (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
166 break;
167 }
168 .EE
169 .in
170 .P
171 According to POSIX.1, it is unspecified whether handlers registered using
172 .BR pthread_atfork (3)
173 are called during the execution of
174 .BR system ().
175 In the glibc implementation, such handlers are not called.
176 .P
177 Before glibc 2.1.3, the check for the availability of
178 .I /bin/sh
179 was not actually performed if
180 .I command
181 was NULL;
182 instead it was always assumed to be available,
183 and
184 .BR system ()
185 always returned 1 in this case.
186 Since glibc 2.1.3,
187 this check is performed because,
188 even though
189 POSIX.1-2001 requires a conforming implementation to provide a shell,
190 that shell may not be available or executable
191 if the calling program has previously called
192 .BR chroot (2)
193 (which is not specified by POSIX.1-2001).
194 .P
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.
200 .\"
201 .SS Caveats
202 Do not use
203 .BR system ()
204 from a privileged program
205 (a set-user-ID or set-group-ID program, or a program with capabilities)
206 because strange values for some environment variables
207 might be used to subvert system integrity.
208 For example,
209 .B PATH
210 could be manipulated so that an arbitrary program
211 is executed with privilege.
212 Use the
213 .BR exec (3)
214 family of functions instead, but not
215 .BR execlp (3)
216 or
217 .BR execvp (3)
218 (which also use the
219 .B PATH
220 environment variable to search for an executable).
221 .P
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
226 is bash version 2: as a security measure, bash 2 drops privileges on startup.
227 (Debian uses a different shell,
228 .BR dash (1),
229 which does not do this when invoked as
230 .BR sh .)
231 .P
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.
241 .SH BUGS
242 .\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029)
243 .\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143)
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:
255 .P
256 .in +4n
257 .EX
258 system(" \-unfortunate\-command\-name");
259 .EE
260 .in
261 .SH SEE ALSO
262 .BR sh (1),
263 .BR execve (2),
264 .BR fork (2),
265 .BR sigaction (2),
266 .BR sigprocmask (2),
267 .BR wait (2),
268 .BR exec (3),
269 .BR signal (7)