]>
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 | .\" |
b8efb414 | 31 | .TH SYSTEM 3 2016-10-08 "" "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> | |
37 | .sp | |
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: | |
50 | ||
61100fc0 | 51 | execl("/bin/sh", "sh", "-c", command, (char *) 0); |
7f26d075 MK |
52 | |
53 | .BR system () | |
54 | returns after the command has been completed. | |
55 | ||
fea681da MK |
56 | During execution of the command, |
57 | .B SIGCHLD | |
58 | will be blocked, and | |
59 | .B SIGINT | |
60 | and | |
61 | .B SIGQUIT | |
7f26d075 MK |
62 | will be ignored, in the process that calls |
63 | .BR system () | |
64 | (these signals will be handled according to their defaults inside | |
65 | the child process that executes | |
66 | .IR command ). | |
67 | ||
68 | If | |
dc23fde1 | 69 | .I command |
7f26d075 | 70 | is NULL, then |
dc23fde1 | 71 | .BR system () |
7f26d075 MK |
72 | returns a status indicating whether a shell is available on the system |
73 | .SH RETURN VALUE | |
74 | The return value of | |
75 | .BR system () | |
76 | is one of the following: | |
77 | .IP * 3 | |
78 | If | |
79 | .I command | |
80 | is NULL, then a nonzero value if a shell is available, | |
81 | or 0 if no shell is available. | |
82 | .IP * | |
83 | If a child process could not be created, | |
84 | or its status could not be retrieved, | |
85 | the return value is \-1. | |
86 | .IP * | |
87 | If a shell could not be executed in the child process, | |
88 | then the return value is as though the child shell terminated by calling | |
89 | .BR _exit (2) | |
90 | with the status 127. | |
91 | .IP * | |
92 | If all system calls succeed, | |
93 | then the return value is the termination status of the child shell | |
94 | used to execute | |
95 | .IR command . | |
96 | (The termination status of a shell is the termination status of | |
97 | the last command it executes.) | |
98 | .PP | |
99 | In the last two cases, | |
100 | the return value is a "wait status" that can be examined using | |
101 | the macros described in | |
102 | .BR waitpid (2). | |
103 | (i.e., | |
00e295fb MK |
104 | .BR WIFEXITED (), |
105 | .BR WEXITSTATUS (), | |
7f26d075 | 106 | and so on). |
fea681da | 107 | .PP |
dc23fde1 | 108 | .BR system () |
fea681da | 109 | does not affect the wait status of any other children. |
527c8d41 | 110 | .SH ATTRIBUTES |
130567d4 PH |
111 | For an explanation of the terms used in this section, see |
112 | .BR attributes (7). | |
113 | .TS | |
114 | allbox; | |
115 | lb lb lb | |
116 | l l l. | |
117 | Interface Attribute Value | |
118 | T{ | |
527c8d41 | 119 | .BR system () |
130567d4 PH |
120 | T} Thread safety MT-Safe |
121 | .TE | |
47297adb | 122 | .SH CONFORMING TO |
30acba8a | 123 | POSIX.1-2001, POSIX.1-2008, C89, C99. |
fea681da | 124 | .SH NOTES |
7f26d075 MK |
125 | .BR system () |
126 | provides simplicity and convenience: | |
127 | it handles all of the details of calling | |
128 | .BR fork (2), | |
129 | .BR execl (3), | |
130 | and | |
131 | .BR waitpid (2), | |
132 | as well as the necessary manipulations of signals; | |
133 | in addition, | |
134 | the shell performs the usual substitutions and I/O redirections for | |
135 | .IR command . | |
136 | The main cost of | |
137 | .BR system () | |
138 | is inefficiency: | |
139 | additional system calls are required to create the process that | |
140 | runs the shell and to execute the shell. | |
141 | ||
dc23fde1 MK |
142 | If the |
143 | .B _XOPEN_SOURCE | |
e417acb0 MK |
144 | feature test macro is defined |
145 | (before including | |
146 | .I any | |
147 | header files), | |
148 | then the macros described in | |
7f26d075 | 149 | .BR waitpid (2) |
f87925c6 | 150 | .RB ( WEXITSTATUS (), |
dc23fde1 | 151 | etc.) are made available when including |
c13182ef | 152 | .IR <stdlib.h> . |
dc23fde1 | 153 | .PP |
fea681da | 154 | As mentioned, |
dc23fde1 | 155 | .BR system () |
8bd58774 MK |
156 | ignores |
157 | .B SIGINT | |
158 | and | |
159 | .BR SIGQUIT . | |
1c44bd5b | 160 | This may make programs that call it |
b9560046 | 161 | from a loop uninterruptible, unless they take care themselves |
c13182ef | 162 | to check the exit status of the child. |
7f26d075 | 163 | For example: |
fea681da MK |
164 | .br |
165 | .nf | |
166 | ||
d4949190 | 167 | while (something) { |
fea681da MK |
168 | int ret = system("foo"); |
169 | ||
170 | if (WIFSIGNALED(ret) && | |
171 | (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) | |
172 | break; | |
173 | } | |
174 | .fi | |
175 | .PP | |
176 | Do not use | |
dc23fde1 | 177 | .BR system () |
880f5b4b | 178 | from a program with set-user-ID or set-group-ID privileges, |
dc23fde1 MK |
179 | because strange values for some environment variables |
180 | might be used to subvert system integrity. | |
fea681da MK |
181 | Use the |
182 | .BR exec (3) | |
183 | family of functions instead, but not | |
184 | .BR execlp (3) | |
185 | or | |
186 | .BR execvp (3). | |
dc23fde1 | 187 | .BR system () |
c13182ef | 188 | will not, in fact, work properly from programs with set-user-ID or |
880f5b4b | 189 | set-group-ID privileges on systems on which |
dc23fde1 | 190 | .I /bin/sh |
fea681da MK |
191 | is bash version 2, since bash 2 drops privileges on startup. |
192 | (Debian uses a modified bash which does not do this when invoked as | |
193 | .BR sh .) | |
194 | .PP | |
dc23fde1 MK |
195 | In versions of glibc before 2.1.3, the check for the availability of |
196 | .I /bin/sh | |
197 | was not actually performed if | |
198 | .I command | |
199 | was NULL; instead it was always assumed to be available, and | |
200 | .BR system () | |
201 | always returned 1 in this case. | |
202 | Since glibc 2.1.3, this check is performed because, even though | |
203 | POSIX.1-2001 requires a conforming implementation to provide | |
204 | a shell, that shell may not be available or executable if | |
205 | the calling program has previously called | |
206 | .BR chroot (2) | |
207 | (which is not specified by POSIX.1-2001). | |
fea681da | 208 | .PP |
7f26d075 MK |
209 | It is possible for the shell command to terminate with a status of 127, |
210 | which yields a | |
211 | .BR system () | |
212 | return value that is indistinguishable from the case | |
213 | where a shell could not be executed in the child process. | |
47297adb | 214 | .SH SEE ALSO |
fea681da | 215 | .BR sh (1), |
fb7a9afd | 216 | .BR execve (2), |
c0f12d15 | 217 | .BR fork (2), |
7f26d075 MK |
218 | .BR sigaction (2), |
219 | .BR sigprocmask (2), | |
fea681da | 220 | .BR wait (2), |
7f26d075 MK |
221 | .BR exec (3), |
222 | .BR signal (7) |