execvpe()

Updated: April 19, 2023

Execute a file

Synopsis:

#include <process.h>

int execvpe( const char * file,
             char * const argv[],
             char * const 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.
argv
An array of character pointers to NULL-terminated strings. Your application must ensure that the last member of this array is a NULL pointer. These strings constitute the argument list available to the new process image. The value in argv[0] must point to a filename that's associated with the process being started. Neither argv nor the value in argv[0] can be NULL.
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:

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

The execvpe() 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.

Note:
  • In order to start the new process image, your process must have the PROCMGR_AID_SPAWN ability enabled. For more information, see procmgr_ability().
  • 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 QNX Neutrino User's Guide.

The execvpe() 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 process is started with the argument specified in argv, a NULL-terminated array of NULL-terminated strings. The argv[0] entry should point to a filename associated with the program being loaded. The argv argument can't be NULL but argv[0] can be NULL if no arguments are required.

The new process image'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's 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 if the program can't 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 image. Otherwise, if the set-user ID mode bit is set, the effective user ID of the new process image 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 image is set to the group ID of file. The real user ID, real group ID and supplementary group IDs of the new process image remain the same as those of the calling process. The effective user ID and effective group ID of the new process image are saved as the saved set-user ID and the saved set-group ID used by setuid().

If the calling process had locked any memory, the locks are released.

exec*() summary

Function Description POSIX?
execl() NULL-terminated argument list Yes
execle() NULL-terminated argument list, specify the new process image's environment Yes
execlp() NULL-terminated argument list, search for the new process image file in PATH Yes
execlpe() NULL-terminated argument list, search for the new process image file in PATH, specify the new process image's environment No
execv() NULL-terminated array of arguments Yes
execve() NULL-terminated array of arguments, specify the new process image's environment Yes
execvp() NULL-terminated array of arguments, search for the new process image file in PATH Yes
execvpe() NULL-terminated array of arguments, search for the new process image file in PATH, specify the new process image's environment No

Returns:

When execvpe() 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.
EACCES
The calling process doesn't have permission to search a directory listed in path, or it doesn't have permission to execute path, or path's filesystem was mounted with the ST_NOEXEC flag.
EINVAL
Either argv or the value in argv[0] is NULL.
ELOOP
Too many levels of symbolic links or prefixes.
EMFILE
Insufficient resources available to load the new executable image or to remap file descriptors.
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
The new process image requires more memory than is allowed by the hardware or system-imposed memory management constraints.
ENOTDIR
A component of file isn't a directory.
EPERM
The calling process doesn't have the required permission (see procmgr_ability()), or an underlying call to mmap() failed because it attempted to set PROT_EXEC for a region of memory covered by an untrusted memory-mapped file.
ETXTBSY
The text file that you're trying to execute is busy (e.g., it might be open for writing).

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes