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
const char *const argv[]; // array of arguments
const 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. The shell, sh, has a limit of 10 open file handles.

There are various forms of the exec functions:

• The l form of the exec functions (execl...()) contain an argument list that's terminated by a NULL pointer. The argument arg0 should point to a filename that's associated with the program being loaded.
• 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's 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.
• 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 isn't 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 exec functions isn't 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.
• 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

• execl()
• execle()
• execlp()
• execlpe()

or as a vector of pointers for

• execv()
• execve()
• execvp()
• execvpe()

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's 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 flags field of the qnx_spawn_options are effectively ignored when using the exec... functions because you're not creating a new process.

If you want files opened by the original process to be closed in the new one, use fcntl() to set the FD_CLOEXEC file-descriptor flag before calling the exec... function.

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 qnx_spawn() for a description of possible errno values.

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

See also:

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