system(3S) system(3S)
NAME
system - issue a shell command
SYNOPSIS
#include <stdlib.h>
int system(const char *command);
DESCRIPTION
system() causes the string command to be given to the shell [see
sh(1)] as input, as if the string had been typed as a command at a
terminal. The current process waits until the shell command has com-
pleted, then returns the exit status of the shell in the format speci-
fied by waitpid().
If command is a null pointer, system() checks if /sbin/sh exists and
is executable. If /sbin/sh is available, system() returns nonzero;
otherwise it returns zero.
system() fails if:
EINTR system() was interrupted by a signal [XPG3].
EAGAIN Insufficient memory on the system to start another process,
or the maximum number of processes executable on the system
level or for one user (CHILDMAX) has been reached.
RESULT
system() forks to create a child process that in turn execs /sbin/sh
in order to execute command. If the fork()or exec() fails, system()
returns a negative value and sets errno.
NOTES
If the return value of system() is not -1, its value can be decoded
through the use of the macros described in sys/wait.h. For conveni-
ence, these macros are also provided in stdlib.h.
Note that, while system() must ignore SIGINT and SIGQUIT and block
SIGCHLD while waiting for the child to terminate, the handling of sig-
nals in the executed command is as specified by fork() and exec(). For
example, if SIGINT is being caught or is set to SIGDFL when system()
is called, then the child will be started with SIGINT handling set to
SIGDFL.
Ignoring SIGINT and SIGQUIT in the parent process in XPG3 mode
prevents coordination problems (two processes reading from the same
terminal, for example) when the executed command ignores or catches
one of the signals. It is also usually the correct action when the
user has given a command to the application to be executed synchro-
nously (as in the "!" command in many interactive applications). In
either case, the signal should be delivered only to the child process,
not to the application itself. There is one situation where ignoring
Page 1 Reliant UNIX 5.44 Printed 11/98
system(3S) system(3S)
the signals might have less than the desired effect. This is when the
application uses system() to perform some task invisible to the user.
If the user typed the interrupt character (^C for example) while sys-
tem() is being used in this way, one would expect the application to
be killed, but only the executed command will be killed. Applications
that use system() in this way should carefully check the return status
from system() to see if the executed command was successful, and
should take appropriate action when the command fails.
Blocking SIGCHLD while waiting for the child to terminate prevents the
application from catching the signal and obtaining status from
system()'s child process before system() can get the status itself.
The context in which the utility is ultimately executed may differ
from that in which the system() function was called. For example, file
descriptors that have the FDCLOEXEC flag set will be closed, and the
process ID and parent process ID will be different. Also, if the exe-
cuted utility changes its environment variables or its current working
directory, that change will not be reflected in the caller's context.
There is no defined way for an application to find the specific path
for the shell. However, confstr() can provide a value for PATH that is
guaranteed to find the sh utility.
The shell applies restrictions to the use of "s bits": If real
(uid/gid) and effective (euid/egid) user/group numbers are different
and (euid/egid) is less than 100 and egid is not set to "1",
(euid/egid) are assigned the same numbers as (uid/gid).
SEE ALSO
sh(1), exec(2), wait(2).
Page 2 Reliant UNIX 5.44 Printed 11/98