execlpe()

Execute a file

Synopsis:

#include <process.h>

int execlpe( const char * file, 
             const char * arg0, 
             const char * arg1,
             …
             const char * argn, 
             NULL,
             const char * envp[] );

Arguments:

file

Used to construct a pathname that identifies the new process image file. If the file argument contains a slash character, the file argument is used as the pathname for the file. Otherwise, the path prefix for this file is obtained by a search of the directories passed as the environment variable PATH.

arg0…argn

Pointers to NULL-terminated character strings. These strings constitute the argument list available to the new process image. Terminate the list terminated with a NULL pointer. The arg0 argument must point to a filename that's associated with the process.

envp

An array of character pointers to NULL-terminated strings. These strings constitute the environment for the new process image. Terminate the envp array with a NULL pointer.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

---

See execl() for further information on the exec*() family of functions.

---

The execlpe() function replaces the current process image with a new process image specified by file. The new image is constructed from a regular, executable file called the new process image file. No return is made because the calling process image is replaced by the new process image.

---

If the new child process is a shell script, the first line must start with #!, followed by the path of the program to run to interpret the script, optionally followed by one argument. The script must also be marked as executable. For more information, see “The first line” in the Writing Shell Scripts chapter of the Neutrino User's Guide.

---

The execlpe() function uses the 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 from the path specified in file.

The process is started with the arguments specified in the NULL-terminated arguments arg1…argn. arg0 should point to a filename associated with the program being loaded. Only arg0 is required, arg1…argn are optional.

The new process's environment is specified in envp, a NULL-terminated array of NULL-terminated strings. envp cannot be NULL, but envp[0] can be a NULL pointer if no environment strings are passed.

Each pointer in envp points to a string in the form:

variable=value

that is used to define an environment variable.

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

An error is detected when the program cannot be found.

If the file is on a filesystem mounted with the ST_NOSUID flag set, the effective user ID, effective group ID, saved set-user ID and saved set-group ID are unchanged for the new process. Otherwise, if the set-user ID mode bit is set, the effective user ID of the new process is set to the owner ID of file. Similarly, if the set-group ID mode bit is set, the effective group ID of the new process is set to the group ID of file. The real user ID, real group ID and supplementary group IDs of the new process remain the same as those of the calling process. The effective user ID and effective group ID of the new process are saved as the saved set-user ID and the saved set-group ID used by setuid().

exec*() summary

Returns:

When execlpe() is successful, it doesn't return; otherwise, it returns -1 and sets errno.

Errors:

E2BIG

The argument list and the environment is larger than the system limit of ARG_MAX bytes.

EACCESS

The calling process doesn't have permission to search a directory listed in file, or it doesn't have permission to execute file, or file's filesystem was mounted with the ST_NOEXEC flag.

ELOOP

Too many levels of symbolic links or prefixes.

ENAMETOOLONG

The length of file or an element of the PATH environment variable exceeds PATH_MAX.

ENOENT

One or more components of the pathname don't exist, or the file argument points to an empty string.

ENOMEM

There's insufficient memory available to create the new process.

ENOTDIR

A component of file isn't a directory.

Classification:

QNX 4

See also:

abort(), atexit(), errno, execl(), execle(), execlp(), execv(), execve(), execvp(), execvpe(), _exit(), exit(), getenv(), main(), putenv(), spawn(), spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnp(), spawnv(), spawnve(), spawnvp(), spawnvpe(), system()

Processes and Threads chapter of Getting Started with QNX Neutrino