original/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  2014-06-13 "" "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 .SS Multithreading (see pthreads(7))
 112 The
 113 .BR system ()
 114 function is thread-safe.
 115 .SH CONFORMING TO
 116 C89, C99, POSIX.1-2001.
 117 .SH NOTES
 118 .BR system ()
 119 provides simplicity and convenience:
 120 it handles all of the details of calling
 121 .BR fork (2),
 122 .BR execl (3),
 123 and
 124 .BR waitpid (2),
 125 as well as the necessary manipulations of signals;
 126 in addition,
 127 the shell performs the usual substitutions and I/O redirections for
 128 .IR command .
 129 The main cost of
 130 .BR system ()
 131 is inefficiency:
 132 additional system calls are required to create the process that
 133 runs the shell and to execute the shell.
 134
 135 If the
 136 .B _XOPEN_SOURCE
 137 feature test macro is defined
 138 (before including
 139 .I any
 140 header files),
 141 then the macros described in
 142 .BR waitpid (2)
 143 .RB ( WEXITSTATUS (),
 144 etc.) are made available when including
 145 .IR <stdlib.h> .
 146 .PP
 147 As mentioned,
 148 .BR system ()
 149 ignores
 150 .B SIGINT
 151 and
 152 .BR SIGQUIT .
 153 This may make programs that call it
 154 from a loop uninterruptible, unless they take care themselves
 155 to check the exit status of the child.
 156 For example:
 157 .br
 158 .nf
 159
 160     while (something) {
 161         int ret = system("foo");
 162
 163         if (WIFSIGNALED(ret) &&
 164             (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT))
 165                 break;
 166     }
 167 .fi
 168 .PP
 169 Do not use
 170 .BR system ()
 171 from a program with set-user-ID or set-group-ID privileges,
 172 because strange values for some environment variables
 173 might be used to subvert system integrity.
 174 Use the
 175 .BR exec (3)
 176 family of functions instead, but not
 177 .BR execlp (3)
 178 or
 179 .BR execvp (3).
 180 .BR system ()
 181 will not, in fact, work properly from programs with set-user-ID or
 182 set-group-ID privileges on systems on which
 183 .I /bin/sh
 184 is bash version 2, since bash 2 drops privileges on startup.
 185 (Debian uses a modified bash which does not do this when invoked as
 186 .BR sh .)
 187 .PP
 188 In versions of glibc before 2.1.3, the check for the availability of
 189 .I /bin/sh
 190 was not actually performed if
 191 .I command
 192 was NULL; instead it was always assumed to be available, and
 193 .BR system ()
 194 always returned 1 in this case.
 195 Since glibc 2.1.3, this check is performed because, even though
 196 POSIX.1-2001 requires a conforming implementation to provide
 197 a shell, that shell may not be available or executable if
 198 the calling program has previously called
 199 .BR chroot (2)
 200 (which is not specified by POSIX.1-2001).
 201 .PP
 202 It is possible for the shell command to terminate with a status of 127,
 203 which yields a
 204 .BR system ()
 205 return value that is indistinguishable from the case
 206 where a shell could not be executed in the child process.
 207 .SH SEE ALSO
 208 .BR sh (1),
 209 .BR sigaction (2),
 210 .BR sigprocmask (2),
 211 .BR fork (2),
 212 .BR wait (2),
 213 .BR exec (3),
 214 .BR signal (7)