execlp()
Execute a file
Synopsis:
#include <unistd.h>
int execlp( const char * file,
const char * arg0,
const char * arg1,
…
const char * argn,
NULL );
This function is declared in <process.h>, which <unistd.h> includes.
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. You must terminate the list with a NULL pointer. The arg0 argument must point to a filename that's associated with the process and cannot be NULL.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The execlp() 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.
When a C-language program is executed as a result of this call, it's entered as a C-language function call as follows:
int main (int argc, char *argv[]);
where argc is the argument count and argv is an array of character pointers to the arguments themselves. In addition, the following variable:
extern char **environ;
is initialized as a pointer to an array of character pointers to the environment strings. The argv and environ arrays are each terminated by a null pointer. The null pointer terminating the argv array isn't counted in argc.
Multithreaded applications shouldn't use the environ variable to access or modify any environment variable while any other thread is concurrently modifying any environment variable. A call to any function dependent on any environment variable is considered a use of the environ variable to access that environment variable.
The arguments specified by a program with one of the exec functions are passed on to the new process image in the corresponding main() arguments.
If the process image file isn't a valid executable object, the contents of the file are passed as standard input to a command interpreter conforming to the system() function. In this case, the command interpreter becomes the new process image.
The number of bytes available for the new process image's combined argument and environment lists is ARG_MAX.
File descriptors open in the calling process image remain open in the new process image, except for when fcntl()'s FD_CLOEXEC flag is set. For those file descriptors that remain open, all attributes of the open file description, including file locks remain unchanged. If a file descriptor is closed for this reason, file locks are removed as described by close() while locks not affected by close() aren't changed.
Directory streams open in the calling process image are closed in the new process image.
Signals set to SIG_DFL in the calling process are set to the default action in the new process image. Signals set to SIG_IGN by the calling process images are ignored by the new process image. Signals set to be caught by the calling process image are set to the default action in the new process image.
After a successful call, any functions previously registered by atexit() are no longer registered.
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 user 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()).
Any shared memory segments attached to the calling process image aren't attached to the new process image. If the calling process had locked any memory, the locks are released.
The new process image doesn't inherit the calling process's default timer tolerance (set by a call to procmgr_timer_tolerance()).
The new process image also inherits at least the following attributes from the calling process image:
- process ID
- parent process ID
- process group ID
- session membership
- real user ID
- real group ID
- supplementary group IDs
- time left until an alarm clock signal (see alarm())
- current working directory
- root directory
- file mode creation mask (see umask())
- process signal mask (see sigprocmask())
- pending signal (see sigpending())
- tms_utime, tms_stime, tms_cutime, and tms_cstime (see times())
- resource limits
- controlling terminal
- interval timers.
A call to this function from a process with more than one thread results in all threads being terminated and the new executable image being loaded and executed. No destructor functions are called.
Upon successful completion, the st_atime field of the file is marked for update. If the exec* failed but was able to locate the process image file, whether the st_atime field is marked for update is undefined. On success, the process image file is considered to be opened with open(). The corresponding close() is considered to occur at a time after this open, but before process termination or successful completion of a subsequent call to one of the exec* functions.
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 execlp() 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
- The arg0 argument 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:
Safety: | |
---|---|
Cancellation point | No |
Signal handler | No |
Thread | Yes |