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