diff options
Diffstat (limited to 'man3/system.3')
| -rw-r--r-- | man3/system.3 | 269 |
1 files changed, 0 insertions, 269 deletions
diff --git a/man3/system.3 b/man3/system.3 deleted file mode 100644 index 08ffb07..0000000 --- a/man3/system.3 +++ /dev/null @@ -1,269 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |