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

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:

• The l form of the spawn functions (spawnl...()) contain an argument list terminated by a NULL pointer. The argument arg0 should point to a filename that is associated with the program being loaded.
• The v form of the spawn functions (spawnv...()) contain a pointer to an argument vector. The value in argv[0] should point to a filename that is associated with the program being loaded. The last member of argv must be a NULL pointer. The value of argv cannot be NULL.
• The p form of the spawn functions (spawnlp...(), spawnvp...()) use paths listed in the PATH environment variable to locate the program to be loaded provided that the following conditions are met:
  • The argument file identifies the name of program to be loaded.
  • If no path character (/) is included in the name, an attempt is made to load the program from one of the paths in the PATH environment variable.
  • If PATH is not defined, the current working directory is used.
  • If a path character (/) is included in the name, the program is loaded as in the following point.
• If a p form of the spawn functions is not used, path must identify the program to be loaded, including a path, if required. Unlike the p form of the spawn functions, only one attempt is made to locate and load the program.
• The e form of the spawn functions (spawn...e()) pass a pointer to a new environment for the program being loaded. The argument envp is an array of character pointers to null-terminated strings. The array of pointers is terminated by a NULL pointer. The value of envp cannot be NULL, but envp[0] can be a NULL pointer, if no environment strings are passed.

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

See also:

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