Debian Codegraph @

upstream/debian-trixie/man3/system.3

raw
1 '\" t
2 .\" Copyright (c) 1993 by Thomas Koenig ([email protected])
3 .\" and Copyright (c) 2014 by Michael Kerrisk <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith ([email protected])
8 .\" Modified 11 May 1998 by Joseph S. Myers ([email protected])
9 .\" Modified 14 May 2001, 23 Sep 2001 by aeb
10 .\" 2004-12-20, mtk
11 .\"
12 .TH system 3 2024-05-02 "Linux man-pages 6.9.1"
13 .SH NAME
14 system \- execute a shell command
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <stdlib.h>
21 .P
22 .BI "int system(const char *" "command" );
23 .fi
24 .SH DESCRIPTION
25 The
26 .BR system ()
27 library function behaves as if it used
28 .BR fork (2)
29 to create a child process that executed the shell command specified in
30 .I command
31 using
32 .BR execl (3)
33 as follows:
34 .P
35 .in +4n
36 .EX
37 execl("/bin/sh", "sh", "\-c", command, (char *) NULL);
38 .EE
39 .in
40 .P
41 .BR system ()
42 returns after the command has been completed.
43 .P
44 During execution of the command,
45 .B SIGCHLD
46 will be blocked, and
47 .B SIGINT
48 and
49 .B SIGQUIT
50 will be ignored, in the process that calls
51 .BR system ().
52 (These signals will be handled according to their defaults inside
53 the child process that executes
54 .IR command .)
55 .P
56 If
57 .I command
58 is NULL, then
59 .BR system ()
60 returns a status indicating whether a shell is available on the system.
61 .SH RETURN VALUE
62 The return value of
63 .BR system ()
64 is one of the following:
65 .IP \[bu] 3
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.
70 .IP \[bu]
71 If a child process could not be created,
72 or its status could not be retrieved,
73 the return value is \-1 and
74 .I errno
75 is set to indicate the error.
76 .IP \[bu]
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.
81 .IP \[bu]
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.)
88 .P
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.,
94 .BR WIFEXITED (),
95 .BR WEXITSTATUS (),
96 and so on).
97 .P
98 .BR system ()
99 does not affect the wait status of any other children.
100 .SH ERRORS
101 .BR system ()
102 can fail with any of the same errors as
103 .BR fork (2).
104 .SH ATTRIBUTES
105 For an explanation of the terms used in this section, see
106 .BR attributes (7).
107 .TS
108 allbox;
109 lbx lb lb
110 l l l.
111 Interface Attribute Value
112 T{
113 .na
114 .nh
115 .BR system ()
116 T} Thread safety MT-Safe
117 .TE
118 .SH STANDARDS
119 C11, POSIX.1-2008.
120 .SH HISTORY
121 POSIX.1-2001, C89.
122 .SH NOTES
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.
139 .P
140 If the
141 .B _XOPEN_SOURCE
142 feature test macro is defined
143 (before including
144 .I any
145 header files),
146 then the macros described in
147 .BR waitpid (2)
148 .RB ( WEXITSTATUS (),
149 etc.) are made available when including
150 .IR <stdlib.h> .
151 .P
152 As mentioned,
153 .BR system ()
154 ignores
155 .B SIGINT
156 and
157 .BR SIGQUIT .
158 This may make programs that call it
159 from a loop uninterruptible, unless they take care themselves
160 to check the exit status of the child.
161 For example:
162 .P
163 .in +4n
164 .EX
165 while (something) {
166 int ret = system("foo");
167 \&
168 if (WIFSIGNALED(ret) &&
169 (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
170 break;
171 }
172 .EE
173 .in
174 .P
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.
180 .P
181 Before glibc 2.1.3, the check for the availability of
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).
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)