system()

execute a system command

Synopsis:

#include <stdlib.h>
int system( const char *command );

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), 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. The shell, sh, has a limit of 10 open file handles.

Returns:

If the value of command is NULL, then the system() function returns zero if the shell isn't 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 couldn't 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 ) == 255, this indicates that the specified command couldn't be run. WEXITSTATUS() is defined in <sys/wait.h>.

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>

void main()
  {
    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 ) );
    }
  }

Classification:

ANSI, POSIX 1003.2

See also:

abort(), atexit(), _bgetcmd(), close(), errno, exec... functions, exit(), _exit(), getcmd(), getenv(), main(), onexit(), putenv(), sigaction(), signal(), spawn... functions, wait(), waitpid()