system()

Arguments:

command

NULL, or the system command that you want to execute; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The behavior of the system() function depends on the value of its command argument:

• If command is NULL, system() determines whether or not a shell is present.
• If command isn't NULL, system() invokes a copy of the shell, and passes the string command to it for processing. This function uses spawn() to load a copy of the shell.

Returns:

• If command is NULL, system() returns zero if the shell isn't present, or a nonzero value if the shell is present.
• If command isn't NULL, system() returns the result of invoking a copy of the shell. If the shell couldn't be loaded, system() returns -1; otherwise, it returns the status of the specified command. 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 didn't 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 OS 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. In particular, see the error codes for spawn().

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, POSIX 1003.1