system — execute a shell command
#include <stdlib.h>
int
system( |
const char *command); |
The system() library
function uses fork(2) to create a child
process that executes the shell command specified in
command using
execl(3) as follows:
execl("/bin/sh", "sh", "−c", command, (char *) NULL);
system() returns after the
command has been completed.
During execution of the command, SIGCHLD will be blocked, and SIGINT and SIGQUIT will be ignored, in the process
that calls system(). (These
signals will be handled according to their defaults inside
the child process that executes command.)
If command is
NULL, then system() returns a
status indicating whether a shell is available on the
system.
The return value of system()
is one of the following:
If command
is NULL, then a nonzero value if a shell is available,
or 0 if no shell is available.
If a child process could not be created, or its
status could not be retrieved, the return value is
−1 and errno is set
to indicate the error.
If a shell could not be executed in the child process, then the return value is as though the child shell terminated by calling _exit(2) with the status 127.
If all system calls succeed, then the return value
is the termination status of the child shell used to
execute command. (The termination
status of a shell is the termination status of the last
command it executes.)
In the last two cases, the return value is a "wait status"
that can be examined using the macros described in waitpid(2). (i.e.,
WIFEXITED(), WEXITSTATUS(), and so on).
system() does not affect the
wait status of any other children.
For an explanation of the terms used in this section, see attributes(7).
| Interface | Attribute | Value |
system() |
Thread safety | MT-Safe |
system() provides simplicity
and convenience: it handles all of the details of calling
fork(2), execl(3), and waitpid(2), as well as the
necessary manipulations of signals; in addition, the shell
performs the usual substitutions and I/O redirections for
command. The main
cost of system() is
inefficiency: additional system calls are required to create
the process that runs the shell and to execute the shell.
If the _XOPEN_SOURCE feature
test macro is defined (before including any header files), then the macros
described in waitpid(2) (WEXITSTATUS(), etc.) are made available
when including <stdlib.h>
As mentioned, system()
ignores SIGINT and SIGQUIT. This may make programs that call
it from a loop uninterruptible, unless they take care
themselves to check the exit status of the child. For
example:
while (something) { int ret = system("foo"); if (WIFSIGNALED(ret) && (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) break; }
According to POSIX.1, it is unspecified whether handlers
registered using pthread_atfork(3) are
called during the execution of system(). In the glibc implementation, such
handlers are not called.
In versions of glibc before 2.1.3, the check for the
availability of /bin/sh was not
actually performed if command was NULL; instead it
was always assumed to be available, and system() always returned 1 in this case.
Since glibc 2.1.3, this check is performed because, even
though POSIX.1-2001 requires a conforming implementation to
provide a shell, that shell may not be available or
executable if the calling program has previously called
chroot(2) (which is not
specified by POSIX.1-2001).
It is possible for the shell command to terminate with a
status of 127, which yields a system() return value that is
indistinguishable from the case where a shell could not be
executed in the child process.
Do not use system() from a
privileged program (a set-user-ID or set-group-ID program,
or a program with capabilities) because strange values for
some environment variables might be used to subvert system
integrity. For example, PATH
could be manipulated so that an arbitrary program is
executed with privilege. Use the exec(3) family of
functions instead, but not execlp(3) or execvp(3) (which also use
the PATH environment variable
to search for an executable).
system() will not, in
fact, work properly from programs with set-user-ID or
set-group-ID privileges on systems on which /bin/sh is bash version 2: as a security
measure, bash 2 drops privileges on startup. (Debian uses a
different shell, dash(1), which does not do
this when invoked as sh.)
Any user input that is employed as part of command should be
carefully sanitized, to
ensure that unexpected shell commands or command options
are not executed. Such risks are especially grave when
using system() from a
privileged program.
If the command name starts with a hyphen, sh(1) interprets the command
name as an option, and the behavior is undefined. (See the
−c option to sh(1).) To work around this
problem, prepend the command with a space as in the following
call:
system(" −unfortunate−command−name");
This page is part of release 5.11 of the Linux man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
|
Copyright (c) 1993 by Thomas Koenig (ig25rz.uni-karlsruhe.de) and Copyright (c) 2014 by Michael Kerrisk <mtk.manpagesgmail.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. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Since the Linux kernel and libraries are constantly changing, this manual page may be incorrect or out-of-date. The author(s) assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. The author(s) may not have taken the same level of care in the production of this manual, which is licensed free of charge, as they might when working professionally. Formatted or processed versions of this manual, if unaccompanied by the source, must acknowledge the copyright and authors of this work. %%%LICENSE_END Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faithcs.unc.edu) Modified 11 May 1998 by Joseph S. Myers (jsm28cam.ac.uk) Modified 14 May 2001, 23 Sep 2001 by aeb 2004-12-20, mtk |