system()

Execute a system command

Synopsis:

#include <stdlib.h>

int system( const char * command );

Library:

libc

Description:

If the value of command is NULL, then the system() function determines whether or not a shell is present. On a POSIX 1003.2 system (for example, QNX 4 and QNX 6), the shell is always assumed present, and system(NULL) always returns a nonzero value.

Otherwise, the system() function invokes a copy of the shell, and passes the string command to it for processing. This function uses spawnlp() to load a copy of the shell.

The shell used is always /bin/sh, regardless of the setting of the SHELL environment variable, because applications may rely on features of the standard shell, and may fail as a result of running a different shell. This means that any command that can be entered to QNX can be executed, including programs, QNX commands and shell scripts. The exec*() and spawn*() functions can only cause programs to be executed.

Returns:

If the value of command is NULL, then the system() function returns zero if the shell is not present, a nonzero value if the shell is present. This implementation always returns a nonzero value.

Otherwise, the system() function returns the result of invoking a copy of the shell. It returns -1 if the shell could not be loaded; otherwise, the status of the specified command is returned. Use the WEXITSTATUS() macro to determine the low-order 8 bits of the termination status of the process.

For example, assume that status is the value returned by system(). If WEXITSTATUS( status ) returns 255, either the specified command returned a termination status of 255, or the shell did not exit (i.e. it died from a signal or couldn't be started at all) and the return value was 255 due to implementation details. For example, under QNX and most Unix systems, the value is 255 if status is -1, which indicates that the shell couldn't be executed. WEXITSTATUS() is defined in <sys/wait.h>.

For information about macros that extract information from the value returned by system(), see "Status macros" in the description of wait().

When an error has occurred, errno contains a value that indicates the type of error that has been detected.

Examples:

#include <stdlib.h>
#include <stdio.h>
#include <sys/wait.h>

int main( void )
  {
    int rc;

    rc = system( "ls" );
    if( rc == -1 ) {
      printf( "shell could not be run\n" );
    } else {
      printf( "result of running command is %d\n",
          WEXITSTATUS( rc ) );
    }
    return EXIT_SUCCESS;
  }

Classification:

ANSI

See also:

abort(), atexit(), close(), errno, execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), exit(), _exit(), getenv(), main(), putenv(), sigaction(), signal(), spawn(), spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnp(), spawnv(), spawnve(), spawnvp(), spawnvpe(), wait(), waitpid()