exec functions

load and execute a new child process

Synopsis:

#include <process.h>
int execl(   path, arg0, arg1..., argn, NULL );
int execle(  path, arg0, arg1..., argn, NULL,
             envp );
int execlp(  file, arg0, arg1..., argn, NULL );
int execlpe( file, arg0, arg1..., argn, NULL,
             envp );
int execv(   path, argv );
int execve(  path, argv, envp );
int execvp(  file, argv );
int execvpe( file, argv, envp );

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 exec() functions load and execute a new child process, named by path or file. If the child process is successfully loaded, it replaces the current process in memory. No return is made to the original program.

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.

  1. The “l” form of the exec() functions (execl...()) contain an argument list that is 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 exec() functions (execv...()) 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 exec() functions (execlp...(), execvp...()) 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 exec() functions is not used, path must identify the program to be loaded, including a path, if required. Unlike the “p” form of the exec() functions, only one attempt is made to locate and load the program.
  5. The “e” form of the exec() functions (exec...e()) passes 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 exec...() call.

The arguments may be passed as a list of arguments for

or as a vector of pointers for

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 execl(), execlp(), execv(), and execvp() functions. The execle(), execlpe(), execve() and execvpe() 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 QNX env utility, or by the successful execution of the putenv() or setenv() functions. 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.

The execvpe() and execlpe() functions are extensions to POSIX 1003.1.

Returns:

When the invoked program is successfully initiated, no return occurs. When an error is detected while invoking the indicated program, exec...() 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(), errno, exit(), _exit(), getcmd(), getenv(), main(), putenv(), qnx_spawn(), qnx_spawn_options, spawn... functions, system()

Examples:

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

execl( "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
            };

execle( "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 };

execv( "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:

POSIX 1003.1 with extensions

Systems:

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