.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
-.\" License.
+.\" %%%LICENSE_END
+.\"
.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
.\" Modified 14 May 2001, 23 Sep 2001 by aeb
.\" 2004-12-20, mtk
.\"
-.TH SYSTEM 3 2010-09-10 "" "Linux Programmer's Manual"
+.TH SYSTEM 3 2014-06-13 "" "Linux Programmer's Manual"
.SH NAME
system \- execute a shell command
.SH SYNOPSIS
.BI "int system(const char *" "command" );
.fi
.SH DESCRIPTION
+The
.BR system ()
-executes a command specified in
+library function uses
+.BR fork (2)
+to create a child process that executes the shell command specified in
.I command
-by calling
-.BR "/bin/sh \-c"
-.IR command ,
-and returns after the command has been completed.
+using
+.BR execl (3)
+as follows:
+
+ execl("/bin/sh", "sh", "-c", command, (char *) 0);
+
+.BR system ()
+returns after the command has been completed.
+
During execution of the command,
.B SIGCHLD
will be blocked, and
.B SIGINT
and
.B SIGQUIT
-will be ignored.
-.SH "RETURN VALUE"
-The value returned is \-1 on error (e.g.,
-.BR fork (2)
-failed),
-and the return status of the command otherwise.
-This latter return status is in the format
-specified in
-.BR wait (2).
-Thus, the exit code of the command will be
-.IR WEXITSTATUS(status) .
-In case
-.I "/bin/sh"
-could not be executed, the exit status will be that of
-a command that does
-.IR exit(127) .
-.PP
-If the value of
+will be ignored, in the process that calls
+.BR system ()
+(these signals will be handled according to their defaults inside
+the child process that executes
+.IR command ).
+
+If
.I command
-is NULL,
+is NULL, then
+.BR system ()
+returns a status indicating whether a shell is available on the system
+.SH RETURN VALUE
+The return value of
.BR system ()
-returns nonzero if the shell is available, and zero if not.
+is one of the following:
+.IP * 3
+If
+.I command
+is NULL, then a nonzero value if a shell is available,
+or 0 if no shell is available.
+.IP *
+If a child process could not be created,
+or its status could not be retrieved,
+the return value is \-1.
+.IP *
+If a shell could not be executed in the child process,
+then the return value is as though the child shell terminated by calling
+.BR _exit (2)
+with the status 127.
+.IP *
+If all system calls succeed,
+then the return value is the termination status of the child shell
+used to execute
+.IR command .
+(The termination status of a shell is the termination status of
+the last command it executes.)
+.PP
+In the last two cases,
+the return value is a "wait status" that can be examined using
+the macros described in
+.BR waitpid (2).
+(i.e.,
+.BR WIFEXITED ()
+.BR WEXITSTATUS ()
+and so on).
.PP
.BR system ()
does not affect the wait status of any other children.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR system ()
+function is thread-safe.
+.SH CONFORMING TO
C89, C99, POSIX.1-2001.
.SH NOTES
-.PP
+.BR system ()
+provides simplicity and convenience:
+it handles all of the details of calling
+.BR fork (2),
+.BR execl (3),
+and
+.BR waitpid (2),
+as well as the necessary manipulations of signals;
+in addition,
+the shell performs the usual substitutions and I/O redirections for
+.IR command .
+The main cost of
+.BR system ()
+is inefficiency:
+additional system calls are required to create the process that
+runs the shell and to execute the shell.
+
If the
.B _XOPEN_SOURCE
feature test macro is defined
.I any
header files),
then the macros described in
-.BR wait (2)
+.BR waitpid (2)
.RB ( WEXITSTATUS (),
etc.) are made available when including
.IR <stdlib.h> .
This may make programs that call it
from a loop uninterruptible, unless they take care themselves
to check the exit status of the child.
-E.g.
+For example:
.br
.nf
.BR chroot (2)
(which is not specified by POSIX.1-2001).
.PP
-It is possible for the shell command to return 127, so that code is not
-a sure indication that the
-.BR execve (2)
-call failed.
-.SH "SEE ALSO"
+It is possible for the shell command to terminate with a status of 127,
+which yields a
+.BR system ()
+return value that is indistinguishable from the case
+where a shell could not be executed in the child process.
+.SH SEE ALSO
.BR sh (1),
-.BR signal (2),
+.BR sigaction (2),
+.BR sigprocmask (2),
+.BR fork (2),
.BR wait (2),
-.BR exec (3)
+.BR exec (3),
+.BR signal (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
