Technical Reference: Base Operating System and Extensions , Volume 2

system Subroutine

Syntax

#include <stdlib.h>

int system ( String) const char *String;

Description

The system subroutine passes the String parameter to the sh command as input. Then the sh command interprets the String parameter as a command and runs it.

The system subroutine calls the fork subroutine to create a child process that in turn uses the exec l subroutine to run the /usr/bin/sh command, which interprets the shell command contained in the String parameter. When invoked on the Trusted Path, the system subroutine runs the Trusted Path shell (/usr/bin/tsh). The current process waits until the shell has completed, then returns the exit status of the shell. The exit status of the shell is returned in the same manner as a call to the wait or waitpid subroutine, using the structures in the sys/wait.h file.

The system subroutine ignores the SIGINT and SIGQUIT signals, and blocks the SIGCHILD signal while waiting for the command specified by the String parameter to terminate. If this might cause the application to miss a signal that would have killed it, the application should use the value returned by the system subroutine to take the appropriate action if the command terminated due to receipt of a signal. The system subroutine does not affect the termination status of any child of the calling process unless that process was created by the system subroutine. The system subroutine does not return until the child process has terminated.

Parameters

String

Specifies a valid sh shell command.

Note: The system subroutine runs only sh shell commands. The results are unpredictable if the String parameter is not a valid sh shell command.

Return Values

Upon successful completion, the system subroutine returns the exit status of the shell. The exit status of the shell is returned in the same manner as a call to the wait or waitpid subroutine, using the structures in the sys/wait.h file.

If the String parameter is a null pointer and a command processor is available, the system subroutine returns a nonzero value. If the fork subroutine fails or if the exit status of the shell cannot be obtained, the system subroutine returns a value of -1. If the exec l subroutine fails, the system subroutine returns a value of 127. In all cases, the errno global variable is set to indicate the error.

Error Codes

The system subroutine fails if any of the following are true:

EAGAIN	The system-imposed limit on the total number of running processes, either systemwide or by a single user ID, was exceeded.
EINTR	The system subroutine was interrupted by a signal that was caught before the requested process was started. The EINTR error code will never be returned after the requested process has begun.
ENOMEM	Insufficient storage space is available.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The execl subroutine, exit subroutine, fork subroutine, pipe subroutine, wait (wait, waitpid, wait3, or wait364 Subroutine) subroutine, waitpid (wait, waitpid, wait3, or wait364 Subroutine) subroutine.

The sh command.

List of Security and Auditing Subroutines, Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.