system: Execute a command

This function lets you run a z/TPF program segment under a new entry control block (ECB), wait for the program to be completed, and receive its exit status. You can also specify a standard input/output (I/O) stream using the system function. The ECB that calls the system function is also called the parent process; the new ECB that the system function creates is called the child process.

The child process runs in the same subsystem and on the same i-stream as the parent process when the parent process calls the system function.

Format

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

string: A specification of the program to be run, its parameters, and the files to be opened as standard streams.
The string argument has the following format:

Redirection

Where:

name: The 4-character name of the z/TPF program segment to be run. The segment will be run in the same subsystem as the ECB at the time it calls the system function.
parm: A parameter string to be passed to name. Each parameter is delimited by 1 or more space characters.
< or 0<: Indicates redirection of the stdin stream.
> or 1>: Indicates redirection of the stdout stream. If the file exists, it is truncated to zero bytes.
2>: Indicates redirection of the stderr stream. If the file exists, it is truncated to zero bytes.
>> or 1>>: Indicates redirection of the stdout stream without truncation and with output appended to the end of the file.
2>>: Indicates redirection of the stderr stream without truncation and with output appended to the end of the file.
pathname: The name of the file from or to which the stream will be redirected.

The system function formats the string argument by removing and processing the redirections, and placing pointers to the name and parm strings into an argv array so that:

argv[0] contains the address of the name string.
argv[1] to argv[n] contain the addresses of any parm strings, where n is the number of parm strings specified in the string argument passed to the system function.
argv[n+1] contains a null pointer.

The system function then builds a parameter list that it passes to the entry point of the name program. This parameter list contains two parameters:

An int parameter containing the total number of strings in the argv array (n+1).
The address of the argv array.

Normal return

If the argument is a null pointer, the system function returns a value of 1. Otherwise, the system function returns the exit status that is returned when the child process exits. Table 1 lists the exit status for various ways that the child process can exit.

Error return

If the system function detects an error in either the input string or in the running of the child process, it returns a value of -1 and sets errno to one of the following values:

EINVAL: The string parameter does not contain any nonblank characters (string must contain at least a program name) or it contains a vertical bar (|).
Note: The z/TPF system reserves the use of vertical bars for possible future implementation of pipes between processes.
ETPFSYSERR: The child process exited because of a system error.
E2BIG: The string parameter is longer than 4094 bytes.

Table 1. Ways of exiting a z/TPF process and the resulting exit status
How the child process exits	Exit status returned by `system` to parent process
`return` from the initial call to the `main` function.	The returned value of rc (the return code)
`exit(`status`)` function	The value of status
BAL `EXITC RC=R`x	The value contained in `R`x
BAL `EXITC` (with no `RC` parameter)	Indeterminate
`abort()`	`-1`
Any system error that causes the ECB to exit	`-1`, `errno` set to `ETPFSYSERR`

Programming considerations

None.

Examples

The following example creates a new ECB that runs segment QRST. In the main function in QRST, argc will contain the value 4, argv[0] to argv[3] will contain pointers to the strings "QRST", "one", "two", and "three", stdin will read from "my.input", stdout will write to "my.output", and stderr will append to "error.log".

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>

int main(void)
{
    errno = 0;
    if (system("QRST one two three "
               "<my.input >my.output 2>>error.log") == -1 &&
        errno != 0)
    {
        printf("system() error:  %s.\n", strerror(errno));
        exit(8);
    }
    return 0;
}

Related information

See Programming support for z/TPF file system support for more information about z/TPF file system C functions.

See z/TPF C functions overview for more information about z/TPF C/C++ language support.