| .\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
| .\" |
| .\" 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. |
| .\" 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 2004-12-20 "" "Linux Programmer's Manual" |
| .SH NAME |
| system \- execute a shell command |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .sp |
| .BI "int system(const char *" "command" ); |
| .fi |
| .SH DESCRIPTION |
| .BR system () |
| executes a command specified in |
| .I command |
| by calling |
| .BR "/bin/sh \-c" |
| .IR command , |
| and 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 () |
| 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 |
| .I command |
| is NULL, |
| .BR system () |
| returns non-zero if the shell is available, and zero if not. |
| .PP |
| .BR system () |
| does not affect the wait status of any other children. |
| .SH "CONFORMING TO" |
| ANSI C, POSIX.2, 4.3BSD |
| .SH NOTES |
| .PP |
| If the |
| .B _XOPEN_SOURCE |
| feature test macro is defined, then the macros described in |
| .BR wait (2) |
| .RB ( WEXITSTATUS (), |
| etc.) are made available when including |
| .IR <stdlib.h> . |
| .PP |
| As mentioned, |
| .BR 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. E.g. |
| .br |
| .nf |
| |
| while(something) { |
| int ret = system("foo"); |
| |
| if (WIFSIGNALED(ret) && |
| (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) |
| break; |
| } |
| .fi |
| .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 modified bash which does not do this when invoked as |
| .BR sh .) |
| .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 return 127, so that code is not |
| a sure indication that the |
| .BR execve () |
| call failed. |
| .SH "SEE ALSO" |
| .BR sh (1), |
| .BR signal (2), |
| .BR wait (2), |
| .BR exec (3) |