man3/system.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   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
  10 .\" 2004-12-20, mtk
  11 .\"
  12 .TH system 3 (date) "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  35 .in +4n
  36 .EX
  37 execl("/bin/sh", "sh", "\-c", command, (char *) NULL);
  38 .EE
  39 .in
  40 .PP
  41 .BR system ()
  42 returns after the command has been completed.
  43 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .ad l
 108 .nh
 109 .TS
 110 allbox;
 111 lbx lb lb
 112 l l l.
 113 Interface       Attribute       Value
 114 T{
 115 .BR system ()
 116 T}      Thread safety   MT-Safe
 117 .TE
 118 .hy
 119 .ad
 120 .sp 1
 121 .SH STANDARDS
 122 POSIX.1-2001, POSIX.1-2008, C99.
 123 .SH NOTES
 124 .BR system ()
 125 provides simplicity and convenience:
 126 it handles all of the details of calling
 127 .BR fork (2),
 128 .BR execl (3),
 129 and
 130 .BR waitpid (2),
 131 as well as the necessary manipulations of signals;
 132 in addition,
 133 the shell performs the usual substitutions and I/O redirections for
 134 .IR command .
 135 The main cost of
 136 .BR system ()
 137 is inefficiency:
 138 additional system calls are required to create the process that
 139 runs the shell and to execute the shell.
 140 .PP
 141 If the
 142 .B _XOPEN_SOURCE
 143 feature test macro is defined
 144 (before including
 145 .I any
 146 header files),
 147 then the macros described in
 148 .BR waitpid (2)
 149 .RB ( WEXITSTATUS (),
 150 etc.) are made available when including
 151 .IR <stdlib.h> .
 152 .PP
 153 As mentioned,
 154 .BR system ()
 155 ignores
 156 .B SIGINT
 157 and
 158 .BR SIGQUIT .
 159 This may make programs that call it
 160 from a loop uninterruptible, unless they take care themselves
 161 to check the exit status of the child.
 162 For example:
 163 .PP
 164 .in +4n
 165 .EX
 166 while (something) {
 167     int ret = system("foo");
 168
 169     if (WIFSIGNALED(ret) &&
 170         (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
 171             break;
 172 }
 173 .EE
 174 .in
 175 .PP
 176 According to POSIX.1, it is unspecified whether handlers registered using
 177 .BR pthread_atfork (3)
 178 are called during the execution of
 179 .BR system ().
 180 In the glibc implementation, such handlers are not called.
 181 .PP
 182 Before glibc 2.1.3, the check for the availability of
 183 .I /bin/sh
 184 was not actually performed if
 185 .I command
 186 was NULL; instead it was always assumed to be available, and
 187 .BR system ()
 188 always returned 1 in this case.
 189 Since glibc 2.1.3, this check is performed because, even though
 190 POSIX.1-2001 requires a conforming implementation to provide
 191 a shell, that shell may not be available or executable if
 192 the calling program has previously called
 193 .BR chroot (2)
 194 (which is not specified by POSIX.1-2001).
 195 .PP
 196 It is possible for the shell command to terminate with a status of 127,
 197 which yields a
 198 .BR system ()
 199 return value that is indistinguishable from the case
 200 where a shell could not be executed in the child process.
 201 .\"
 202 .SS Caveats
 203 Do not use
 204 .BR system ()
 205 from a privileged program
 206 (a set-user-ID or set-group-ID program, or a program with capabilities)
 207 because strange values for some environment variables
 208 might be used to subvert system integrity.
 209 For example,
 210 .B PATH
 211 could be manipulated so that an arbitrary program
 212 is executed with privilege.
 213 Use the
 214 .BR exec (3)
 215 family of functions instead, but not
 216 .BR execlp (3)
 217 or
 218 .BR execvp (3)
 219 (which also use the
 220 .B PATH
 221 environment variable to search for an executable).
 222 .PP
 223 .BR system ()
 224 will not, in fact, work properly from programs with set-user-ID or
 225 set-group-ID privileges on systems on which
 226 .I /bin/sh
 227 is bash version 2: as a security measure, bash 2 drops privileges on startup.
 228 (Debian uses a different shell,
 229 .BR dash (1),
 230 which does not do this when invoked as
 231 .BR sh .)
 232 .PP
 233 Any user input that is employed as part of
 234 .I command
 235 should be
 236 .I carefully
 237 sanitized, to ensure that unexpected shell commands or command options
 238 are not executed.
 239 Such risks are especially grave when using
 240 .BR system ()
 241 from a privileged program.
 242 .SH BUGS
 243 .\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029)
 244 .\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143)
 245 .\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440)
 246 If the command name starts with a hyphen,
 247 .BR sh (1)
 248 interprets the command name as an option,
 249 and the behavior is undefined.
 250 (See the
 251 .B \-c
 252 option to
 253 .BR sh (1).)
 254 To work around this problem,
 255 prepend the command with a space as in the following call:
 256 .PP
 257 .in +4n
 258 .EX
 259     system(" \-unfortunate\-command\-name");
 260 .EE
 261 .in
 262 .SH SEE ALSO
 263 .BR sh (1),
 264 .BR execve (2),
 265 .BR fork (2),
 266 .BR sigaction (2),
 267 .BR sigprocmask (2),
 268 .BR wait (2),
 269 .BR exec (3),
 270 .BR signal (7)