---

system()

Execute a system command

Synopsis:

#include <stdlib.h>

int system( const char *command );

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 spawnlp() 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 Neutrino 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, POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes

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()

---