man3/system.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   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.
  13 .\"
  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.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  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
  29 .\" 2004-12-20, mtk
  30 .\"
  31 .TH SYSTEM 3  2016-10-08 "" "Linux Programmer's Manual"
  32 .SH NAME
  33 system \- execute a shell command
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <stdlib.h>
  37 .sp
  38 .BI "int system(const char *" "command" );
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR system ()
  43 library function uses
  44 .BR fork (2)
  45 to create a child process that executes the shell command specified in
  46 .I command
  47 using
  48 .BR execl (3)
  49 as follows:
  50
  51     execl("/bin/sh", "sh", "-c", command, (char *) 0);
  52
  53 .BR system ()
  54 returns after the command has been completed.
  55
  56 During execution of the command,
  57 .B SIGCHLD
  58 will be blocked, and
  59 .B SIGINT
  60 and
  61 .B SIGQUIT
  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
  69 .I command
  70 is NULL, then
  71 .BR system ()
  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.,
 104 .BR WIFEXITED (),
 105 .BR WEXITSTATUS (),
 106 and so on).
 107 .PP
 108 .BR system ()
 109 does not affect the wait status of any other children.
 110 .SH ATTRIBUTES
 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{
 119 .BR system ()
 120 T}      Thread safety   MT-Safe
 121 .TE
 122 .SH CONFORMING TO
 123 POSIX.1-2001, POSIX.1-2008, C89, C99.
 124 .SH NOTES
 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
 142 If the
 143 .B _XOPEN_SOURCE
 144 feature test macro is defined
 145 (before including
 146 .I any
 147 header files),
 148 then the macros described in
 149 .BR waitpid (2)
 150 .RB ( WEXITSTATUS (),
 151 etc.) are made available when including
 152 .IR <stdlib.h> .
 153 .PP
 154 As mentioned,
 155 .BR system ()
 156 ignores
 157 .B SIGINT
 158 and
 159 .BR SIGQUIT .
 160 This may make programs that call it
 161 from a loop uninterruptible, unless they take care themselves
 162 to check the exit status of the child.
 163 For example:
 164 .br
 165 .nf
 166
 167     while (something) {
 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
 177 .BR system ()
 178 from a program with set-user-ID or set-group-ID privileges,
 179 because strange values for some environment variables
 180 might be used to subvert system integrity.
 181 Use the
 182 .BR exec (3)
 183 family of functions instead, but not
 184 .BR execlp (3)
 185 or
 186 .BR execvp (3).
 187 .BR system ()
 188 will not, in fact, work properly from programs with set-user-ID or
 189 set-group-ID privileges on systems on which
 190 .I /bin/sh
 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
 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).
 208 .PP
 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.
 214 .SH SEE ALSO
 215 .BR sh (1),
 216 .BR execve (2),
 217 .BR fork (2),
 218 .BR sigaction (2),
 219 .BR sigprocmask (2),
 220 .BR wait (2),
 221 .BR exec (3),
 222 .BR signal (7)