diff options
Diffstat (limited to 'man/man3/system.3')
| -rw-r--r-- | man/man3/system.3 | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/man/man3/system.3 b/man/man3/system.3 new file mode 100644 index 000000000..fb5d0af6b --- /dev/null +++ b/man/man3/system.3 @@ -0,0 +1,269 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2014 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +system \- execute a shell command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "int system(const char *" "command" ); +.fi +.SH DESCRIPTION +The +.BR system () +library function behaves as if it used +.BR fork (2) +to create a child process that executed the shell command specified in +.I command +using +.BR execl (3) +as follows: +.P +.in +4n +.EX +execl("/bin/sh", "sh", "\-c", command, (char *) NULL); +.EE +.in +.P +.BR system () +returns after the command has been completed. +.P +During execution of the command, +.B SIGCHLD +will be blocked, and +.B SIGINT +and +.B SIGQUIT +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 .) +.P +If +.I command +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 () +is one of the following: +.IP \[bu] 3 +If +.I command +is NULL, then a nonzero value if a shell is available, +or 0 if no shell is available. +.IP \[bu] +If a child process could not be created, +or its status could not be retrieved, +the return value is \-1 and +.I errno +is set to indicate the error. +.IP \[bu] +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 \[bu] +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.) +.P +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). +.P +.BR system () +does not affect the wait status of any other children. +.SH ERRORS +.BR system () +can fail with any of the same errors as +.BR fork (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR system () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH NOTES +.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. +.P +If the +.B _XOPEN_SOURCE +feature test macro is defined +(before including +.I any +header files), +then the macros described in +.BR waitpid (2) +.RB ( WEXITSTATUS (), +etc.) are made available when including +.IR <stdlib.h> . +.P +As mentioned, +.BR system () +ignores +.B SIGINT +and +.BR 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: +.P +.in +4n +.EX +while (something) { + int ret = system("foo"); +\& + if (WIFSIGNALED(ret) && + (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) + break; +} +.EE +.in +.P +According to POSIX.1, it is unspecified whether handlers registered using +.BR pthread_atfork (3) +are called during the execution of +.BR system (). +In the glibc implementation, such handlers are not called. +.P +Before glibc 2.1.3, the check for the availability of +.I /bin/sh +was not actually performed if +.I command +was NULL; instead it was always assumed to be available, and +.BR 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 +.BR chroot (2) +(which is not specified by POSIX.1-2001). +.P +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. +.\" +.SS Caveats +Do not use +.BR 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, +.B PATH +could be manipulated so that an arbitrary program +is executed with privilege. +Use the +.BR exec (3) +family of functions instead, but not +.BR execlp (3) +or +.BR execvp (3) +(which also use the +.B PATH +environment variable to search for an executable). +.P +.BR system () +will not, in fact, work properly from programs with set-user-ID or +set-group-ID privileges on systems on which +.I /bin/sh +is bash version 2: as a security measure, bash 2 drops privileges on startup. +(Debian uses a different shell, +.BR dash (1), +which does not do this when invoked as +.BR sh .) +.P +Any user input that is employed as part of +.I command +should be +.I carefully +sanitized, to ensure that unexpected shell commands or command options +are not executed. +Such risks are especially grave when using +.BR system () +from a privileged program. +.SH BUGS +.\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029) +.\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143) +.\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440) +If the command name starts with a hyphen, +.BR sh (1) +interprets the command name as an option, +and the behavior is undefined. +(See the +.B \-c +option to +.BR sh (1).) +To work around this problem, +prepend the command with a space as in the following call: +.P +.in +4n +.EX + system(" \-unfortunate\-command\-name"); +.EE +.in +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR fork (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR wait (2), +.BR exec (3), +.BR signal (7) |