# system

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           system — issue a command
    


## SYNOPSIS



           #include <stdlib.h>
    
           int system(const char *_command_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           If _command_ is a null pointer, the _system_() function shall
           determine whether the host environment has a command processor. If
           _command_ is not a null pointer, the _system_() function shall pass
           the string pointed to by _command_ to that command processor to be
           executed in an implementation-defined manner; this might then
           cause the program calling _system_() to behave in a non-conforming
           manner or to terminate.
    
           The _system_() function shall behave as if a child process were
           created using _fork_(), and the child process invoked the _sh_ utility
           using _execl_() as follows:
    
               execl(<_shell path_ >, "sh", "-c", _command_ , (char *)0);
    
           where <_shell path_ > is an unspecified pathname for the _sh_ utility.
           It is unspecified whether the handlers registered with
           _pthread_atfork_() are called as part of the creation of the child
           process.
    
           The _system_() function shall ignore the SIGINT and SIGQUIT signals,
           and shall block the SIGCHLD signal, while waiting for the command
           to terminate. If this might cause the application to miss a signal
           that would have killed it, then the application should examine the
           return value from _system_() and take whatever action is appropriate
           to the application if the command terminated due to receipt of a
           signal.
    
           The _system_() function shall not affect the termination status of
           any child of the calling processes other than the process or
           processes it itself creates.
    
           The _system_() function shall not return until the child process has
           terminated.
    
           The _system_() function need not be thread-safe.
    


## RETURN VALUE



           If _command_ is a null pointer, _system_() shall return non-zero to
           indicate that a command processor is available, or zero if none is
           available.  The _system_() function shall always return non-zero
           when _command_ is NULL.
    
           If _command_ is not a null pointer, _system_() shall return the
           termination status of the command language interpreter in the
           format specified by _waitpid_().  The termination status shall be as
           defined for the _sh_ utility; otherwise, the termination status is
           unspecified. If some error prevents the command language
           interpreter from executing after the child process is created, the
           return value from _system_() shall be as if the command language
           interpreter had terminated using _exit_(127) or __exit_(127).  If a
           child process cannot be created, or if the termination status for
           the command language interpreter cannot be obtained, _system_()
           shall return -1 and set _errno_ to indicate the error.
    


## ERRORS



           The _system_() function may set _errno_ values as described by
           fork(3p).
    
           In addition, _system_() may fail if:
    
           **ECHILD** The status of the child process created by _system_() is no
                  longer available.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           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 convenience, 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
           signals in the executed command is as specified by _fork_() and
           _exec_.  For example, if SIGINT is being caught or is set to SIG_DFL
           when _system_() is called, then the child is started with SIGINT
           handling set to SIG_DFL.
    
           Ignoring SIGINT and SIGQUIT in the parent process 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 synchronously (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 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 _system_() is being
           used in this way, one would expect the application to be killed,
           but only the executed command is 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 _system_() was called. For example, file
           descriptors that have the FD_CLOEXEC flag set are closed, and the
           process ID and parent process ID are different. Also, if the
           executed utility changes its environment variables or its current
           working directory, that change is not 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.
    
           Using the _system_() function in more than one thread in a process
           or when the SIGCHLD signal is being manipulated by more than one
           thread in a process may produce unexpected results.
    


## RATIONALE



           The _system_() function should not be used by programs that have set
           user (or group) ID privileges. The _fork_() and _exec_ family of
           functions (except _execlp_() and _execvp_()), should be used instead.
           This prevents any unforeseen manipulation of the environment of
           the user that could cause execution of commands not anticipated by
           the calling program.
    
           There are three levels of specification for the _system_() function.
           The ISO C standard gives the most basic. It requires that the
           function exists, and defines a way for an application to query
           whether a command language interpreter exists. It says nothing
           about the command language or the environment in which the command
           is interpreted.
    
           POSIX.1‐2008 places additional restrictions on _system_().  It
           requires that if there is a command language interpreter, the
           environment must be as specified by _fork_() and _exec_.  This
           ensures, for example, that close-on-_exec_ works, that file locks
           are not inherited, and that the process ID is different. It also
           specifies the return value from _system_() when the command line can
           be run, thus giving the application some information about the
           command's completion status.
    
           Finally, POSIX.1‐2008 requires the command to be interpreted as in
           the shell command language defined in the Shell and Utilities
           volume of POSIX.1‐2017.
    
           Note that, _system_(NULL) is required to return non-zero, indicating
           that there is a command language interpreter. At first glance,
           this would seem to conflict with the ISO C standard which allows
           _system_(NULL) to return zero. There is no conflict, however. A
           system must have a command language interpreter, and is non-
           conforming if none is present.  It is therefore permissible for
           the _system_() function on such a system to implement the behavior
           specified by the ISO C standard as long as it is understood that
           the implementation does not conform to POSIX.1‐2008 if
           _system_(NULL) returns zero.
    
           It was explicitly decided that when _command_ is NULL, _system_()
           should not be required to check to make sure that the command
           language interpreter actually exists with the correct mode, that
           there are enough processes to execute it, and so on. The call
           _system_(NULL) could, theoretically, check for such problems as too
           many existing child processes, and return zero. However, it would
           be inappropriate to return zero due to such a (presumably)
           transient condition. If some condition exists that is not under
           the control of this application and that would cause any _system_()
           call to fail, that system has been rendered non-conforming.
    
           Early drafts required, or allowed, _system_() to return with _errno_
           set to **[EINTR]** if it was interrupted with a signal. This error
           return was removed, and a requirement that _system_() not return
           until the child has terminated was added. This means that if a
           _waitpid_() call in _system_() exits with _errno_ set to **[EINTR]** ,
           _system_() must reissue the _waitpid_().  This change was made for two
           reasons:
    
            1. There is no way for an application to clean up if _system_()
               returns **[EINTR]** , short of calling _wait_(), and that could have
               the undesirable effect of returning the status of children
               other than the one started by _system_().
    
            2. While it might require a change in some historical
               implementations, those implementations already have to be
               changed because they use _wait_() instead of _waitpid_().
    
           Note that if the application is catching SIGCHLD signals, it will
           receive such a signal before a successful _system_() call returns.
    
           To conform to POSIX.1‐2008, _system_() must use _waitpid_(), or some
           similar function, instead of _wait_().
    
           The following code sample illustrates how _system_() might be
           implemented on an implementation conforming to POSIX.1‐2008.
    
               #include <signal.h>
               int system(const char *cmd)
               {
                   int stat;
                   pid_t pid;
                   struct sigaction sa, savintr, savequit;
                   sigset_t saveblock;
                   if (cmd == NULL)
                       return(1);
                   sa.sa_handler = SIG_IGN;
                   sigemptyset(&sa.sa_mask);
                   sa.sa_flags = 0;
                   sigemptyset(&savintr.sa_mask);
                   sigemptyset(&savequit.sa_mask);
                   sigaction(SIGINT, &sa, &savintr);
                   sigaction(SIGQUIT, &sa, &savequit);
                   sigaddset(&sa.sa_mask, SIGCHLD);
                   sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock);
                   if ((pid = fork()) == 0) {
                       sigaction(SIGINT, &savintr, (struct sigaction *)0);
                       sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
                       sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0);
                       execl("/bin/sh", "sh", "-c", cmd, (char *)0);
                       _exit(127);
                   }
                   if (pid == -1) {
                       stat = -1; /* errno comes from fork() */
                   } else {
                       while (waitpid(pid, &stat, 0) == -1) {
                           if (errno != EINTR){
                               stat = -1;
                               break;
                           }
                       }
                   }
                   sigaction(SIGINT, &savintr, (struct sigaction *)0);
                   sigaction(SIGQUIT, &savequit, (struct sigaction *)0);
                   sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0);
                   return(stat);
               }
    
           Note that, while a particular implementation of _system_() (such as
           the one above) can assume a particular path for the shell, such a
           path is not necessarily valid on another system. The above example
           is not portable, and is not intended to be.
    
           Note also that the above example implementation is not thread-
           safe.  Implementations can provide a thread-safe _system_()
           function, but doing so involves complications such as how to
           restore the signal dispositions for SIGINT and SIGQUIT correctly
           if there are overlapping calls, and how to deal with cancellation.
           The example above would not restore the signal dispositions and
           would leak a process ID if cancelled. This does not matter for a
           non-thread-safe implementation since canceling a non-thread-safe
           function results in undefined behavior (see _Section 2.9.5.2_ ,
           _Cancellation Points_).  To avoid leaking a process ID, a thread-
           safe implementation would need to terminate the child process when
           acting on a cancellation.
    
           One reviewer suggested that an implementation of _system_() might
           want to use an environment variable such as _SHELL_ to determine
           which command interpreter to use. The supposed implementation
           would use the default command interpreter if the one specified by
           the environment variable was not available. This would allow a
           user, when using an application that prompts for command lines to
           be processed using _system_(), to specify a different command
           interpreter. Such an implementation is discouraged. If the
           alternate command interpreter did not follow the command line
           syntax specified in the Shell and Utilities volume of
           POSIX.1‐2017, then changing _SHELL_ would render _system_() non-
           conforming. This would affect applications that expected the
           specified behavior from _system_(), and since the Shell and
           Utilities volume of POSIX.1‐2017 does not mention that _SHELL_
           affects _system_(), the application would not know that it needed to
           unset _SHELL_.
    


## FUTURE DIRECTIONS



           None.
    


* * *