[Previous]
[Contents]
[Next]

spawn functions

create and execute a new child process

Synopsis:

#include <process.h>
int spawnl(   mode, path, arg0, arg1..., argn, 
              NULL );
int spawnle(  mode, path, arg0, arg1..., argn, 
              NULL, envp );
int spawnlp(  mode, file, arg0, arg1..., argn, 
              NULL );
int spawnlpe( mode, file, arg0, arg1..., argn, 
              NULL, envp );
int spawnv(   mode, path, argv );
int spawnve(  mode, path, argv, envp );
int spawnvp(  mode, file, argv );
int spawnvpe( mode, file, argv, envp );

Description:

The spawn... functions create and execute a new child process, named by path or file (depending on the form of the function used).


Note: If the new process is a shell script, the first line must start with #!, followed by the path and arguments of the shell to be run to interpret the script. The script must also be marked as executable.

The shell, sh, has a limit of 10 open file handles.


The arguments are defined as follows:

int mode
the mode for parent, as described below
const char *path
the filename for the process to run, including the path
const char *file
the filename for the process to run, without the path
const char *arg0,..., *argn
arguments to pass to the new process
char *const argv[]
an array of arguments to pass to the new process
char *const envp[]
an array of environment strings for the new process

The value of mode determines how the program is loaded, and how the invoking program will behave after the invoked program is initiated:

P_WAIT
The invoked program is loaded into available memory, is executed, and then the original program resumes execution.
P_NOWAIT
Causes the current program to execute concurrently with the new child process.
P_NOWAITO
Causes the current program to execute concurrently with the new child process. The wait() function cannot be used to obtain the exit code.
P_OVERLAY
The invoked program replaces the original program in memory and is executed. No return is made to the original program. This is equivalent to calling the appropriate exec... function.

There are various forms of the spawn... functions:

An error is detected when the program cannot be found.

Arguments are passed to the child process by supplying one or more pointers to character strings as arguments in the spawn... call.

The arguments may be passed as a list of arguments (spawnl(), spawnle(), spawnlp() and spawnlpe()) or as a vector of pointers (spawnv(), spawnve(), spawnvp() and spawnvpe()). At least one argument, arg0 or argv[0], must be passed to the child process. By convention, this first argument is a pointer to the name of the program.

If the arguments are passed as a list, there must be a NULL pointer to mark the end of the argument list. Similarly, if a pointer to an argument vector is passed, the argument vector must be terminated by a NULL pointer.

The environment for the invoked program is inherited from the parent process when you use the spawnl(), spawnlp(), spawnv() and spawnvp() functions. The spawnle(), spawnlpe(), spawnve() and spawnvpe() functions allow a different environment to be passed to the child process through the envp argument. The argument envp is a pointer to an array of character pointers, each of which points to a string defining an environment variable. The array is terminated with a NULL pointer. Each pointer locates a character string of the form:

    variable=value

that is used to define an environment variable. If the value of envp is NULL, then the child process inherits the environment of the parent process.

The environment is the collection of environment variables whose values have been defined with the QNX export shell command, the env utility, or by the successful execution of the putenv() or setenv() function. A program may read these values with the getenv()function.

You can use qnx_spawn_options to specify default options for the spawned process, such as the priority and scheduling algorithm.

If you want files opened by the parent process to be closed in the child, use fcntl() to set the FD_CLOEXEC file-descriptor flag before spawning the new process.

Returns:

When the value of mode is P_WAIT, then the return value from spawn... is the exit status of the child process.

When the value of mode is P_NOWAIT or P_NOWAITO, then the return value from spawn... is the process ID of the child process. To obtain the exit code for a process spawned with P_NOWAIT, you must call the wait() function, specifying the process id. The exit code cannot be obtained for a process spawned with P_NOWAITO.

When the value of mode is P_NOWAITO and the process is being spawned on a remote node, then the return value from spawn... is 0 on success.

When an error is detected while invoking the indicated program, spawn... returns -1, and errno is set to indicate the error.

Errors:

See the qnx_spawn() function for a description of possible errno values.

Examples:

#include <stddef.h>
#include <process.h>

spawnl( P_WAIT, "myprog",
    "myprog", "ARG1", "ARG2", NULL );

The preceding invokes myprog as if

myprog ARG1 ARG2

had been entered as a command to QNX . The program will be found if myprog is found in the current working directory.

#include <stddef.h>
#include <process.h>

char *env_list[] = { "SOURCE=MYDATA",
             "TARGET=OUTPUT",
             "lines=65",
             NULL
            };

spawnle( P_WAIT, "myprog",
    "myprog", "ARG1", "ARG2", NULL,
     env_list );

The preceding invokes myprog as if

myprog ARG1 ARG2

had been entered as a command to QNX. The program will be found if myprog is found in the current working directory. The QNX environment for the invoked program will consist of the three environment variables SOURCE, TARGET and lines.

#include <stddef.h>
#include <process.h>

char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL };

spawnv( P_WAIT, "myprog", arg_list );

The preceding invokes myprog as if

myprog ARG1 ARG2

had been entered as a command to QNX . The program will be found if myprog is found in the current working directory.

Classification:

WATCOM

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

abort(), atexit(), exec... functions, exit(), _exit(), fcntl(), getcmd(), getenv(), main(), putenv(), qnx_spawn(), qnx_spawn_options, system(), wait()


[Previous]
[Contents]
[Next]