| .\" 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. |
| .\" |
| .\" 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 (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 2017-09-15 "" "Linux Programmer's Manual" |
| .SH NAME |
| system \- execute a shell command |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .BI "int system(const char *" "command" ); |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR system () |
| library function uses |
| .BR fork (2) |
| to create a child process that executes the shell command specified in |
| .I command |
| using |
| .BR execl (3) |
| as follows: |
| .PP |
| execl("/bin/sh", "sh", "-c", command, (char *) 0); |
| .PP |
| .BR system () |
| returns after the command has been completed. |
| .PP |
| 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 ). |
| .PP |
| 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 * 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 ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lb lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR system () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, C89, C99. |
| .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. |
| .PP |
| 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> . |
| .PP |
| 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: |
| .PP |
| .in +4n |
| .EX |
| while (something) { |
| int ret = system("foo"); |
| |
| if (WIFSIGNALED(ret) && |
| (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) |
| break; |
| } |
| .EE |
| .in |
| .PP |
| 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. |
| .PP |
| In versions of glibc before 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). |
| .PP |
| 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 |
| .PP |
| Do not use |
| .BR system () |
| from a program with set-user-ID or set-group-ID privileges, |
| because strange values for some environment variables |
| might be used to subvert system integrity. |
| Use the |
| .BR exec (3) |
| family of functions instead, but not |
| .BR execlp (3) |
| or |
| .BR execvp (3). |
| .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, since bash 2 drops privileges on startup. |
| (Debian uses a different shell, |
| .BR dash (1), |
| which does not do this when invoked as |
| .BR sh .) |
| .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) |