NAME

system - issue a command

 SYNOPSIS

#include <stdlib.h>

int system(const char *command);

 DESCRIPTION

The system() function passes the string pointed to by command to the host environment to be executed by a command processor in an implementation-dependent manner. If the implementation supports the XCU specification commands, the environment of the executed command will be as if a child process were created using fork(), and the child process invoked the sh utility (see sh in the XCU specification) using execl() as follows:

execl(<shell path>, "sh", "-c", command, (char *)0);

where <shell path> is an unspecified pathname for the sh utility.

The system() function ignores the SIGINT and SIGQUIT signals, and blocks 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 will not affect the termination status of any child of the calling processes other than the process or processes it itself creates.

The system() function will not return until the child process has terminated.

 RETURN VALUE

If command is a null pointer, system() returns non-zero only if a command processor is available.

If command is not a null pointer, system() returns the termination status of the command language interpreter in the format specified by waitpid(). The termination status of the command language interpreter is as specified for the sh utility, except that if some error prevents the command language interpreter from executing after the child process is created, the return value from system() will 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() returns -1 and sets errno to indicate the error.

 ERRORS

The system() function may set errno values as described by fork().

In addition, system() may fail if:

[ECHILD]

The status of the child process created by system() is no longer available.

 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>.

To determine whether or not the XCU specification's environment is present, use:

sysconf(_SC_2_VERSION)

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 will be 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 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 system() was called. For example, file descriptors that have the FD_CLOEXEC flag set will be closed, and the process ID and parent process ID will be different. Also, if the executed 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 that is guaranteed to find the sh utility.

 FUTURE DIRECTIONS

None.

 SEE ALSO

exec, pipe(), waitpid(), <limits.h>, <signal.h>, <stdlib.h>, the XCU specification.

DERIVATION

Derived from Issue 1 of the SVID.