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

int         mode;      /* mode for parent      */
const char *path;      /* file name incl. path */
const char *file;      /* file name            */
const char *arg0,..., 
           *argn;      /* arguments            */
char *const argv[];    /* array of arguments   */
char *const envp[];    /* environment strings  */

Description:

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

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.

1. 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.
2. 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, but argv[0] can be a NULL pointer if no argument strings are passed.
3. 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.
4. 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.
5. 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. These character strings are concatenated with spaces inserted to separate the arguments to form one argument string for the child process. The length of this concatenated string must not exceed 128 bytes for DOS systems.

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

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.

See also:

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

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

Systems:

DOS, Win32, QNX, OS/2 1.x(all), OS/2-32