exec(S)

exec: execl, execv, execle, execve, execlp, execvp -- execute a file

Syntax

cc . . . -lc

#include <unistd.h>

int execl (path, arg0, arg1, ..., argn, (char *)0)
const char *path, *arg0, *arg1, ..., *argn;

int execle (path, arg0, arg1, ..., argn, (char *)0, envp)
const char *path, *arg0, *arg1, ..., *argn;
char *const envp[ ];

int execlp (file, arg0, arg1, ..., argn, (char *)0)
const char *file, *arg0, *arg1, ..., *argn;

int execv (path, argv)
const char *path;
char *const argv[];

int execve (path, argv, envp)
const char *path;
char *const argv[], envp[];

int execvp (file, argv)
const char *file;
char *const argv[];

extern char **environ;

Description

The exec system call in all its forms transforms the calling process into a new process.

The new process may be constructed from an ordinary executable file. Executable files consist of a header (see a.out(FP)), a text segment, and a data segment. The data segment contains an initialized portion and an uninitialized portion (bss). There can be no return from a successful exec because the calling process is overlaid by the new process.

An executable file may also be a text file, either as a ``#! script'' or as a ``shell script.'' A #! script always has #! as its first two characters and must always specify the full path of an existing command interpreter on its #! line. The command interpreter specified on the #! line is loaded to execute the script and replaces the calling process in the memory. If the text file does not have #! as its first two characters, the exec*() system call sets errno to [ENOEXEC] and returns with a return value of -1. Some command interpreters, such as the Bourne and Korn shells (/bin/sh, /bin/ksh), will detect the [ENOEXEC] error value and try to pass the script as input or argument to an invocation of the command interpreter. This functionality differs in execlp(S) and execvp(S) which pass the file to the Bourne shell as an argument if [ENOEXEC] is detected.

Executables created by C programs always use the function main as their entry point. The prototype for main is (arguments are optional):

   main(argc, argv, envp)
   int argc;
   char **argv, **envp;

where argc is the argument count, argv is an array of character pointers to the arguments themselves, and envp is an array of character pointers to the environment strings. As indicated, argc is conventionally at least one, and the first member of the array points to a string containing the name of the file.

The path argument points to a path name that identifies the new process file.

The file argument points to the new process file. The path prefix for this file is obtained by a search of the directories passed as the environment line "PATH="; see environ(M). The environment is supplied by the shell; see sh(C).

arg0, arg1, ..., argn are pointers to null-terminated character strings. These strings constitute the argument list available to the new process. By convention, at least arg0 must be present and point to a string that is the same as path (or its last component).

argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new process. By convention, argv must have at least one member, and it must point to a string that is the same as path (or its last component). argv is terminated by a null pointer.

envp is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process. envp is terminated by a null pointer. For execl, execlp, execv and execvp, the C run-time start-off routine places a pointer to the environment of the calling process in the global cell:

   extern char **environ;

and it is used to pass the environment of the calling process to the new process. The environ array should not be accessed directly by an application. Instead, the use of a library routine, such as getenv(S), is recommended.

File descriptors open in the calling process remain open in the new process, except for those whose close-on-exec flag is set; see fcntl(S). For those file descriptors that remain open, the file pointer is unchanged.

Signals set to terminate the calling process are set to terminate the new process. Signals set to be ignored by the calling process are set to be ignored by the new process. Signals set to be caught by the calling process are set to terminate the new process; see sigaction(S).

For signals set by sigset, exec ensures that the new process has the same system signal action for each signal type whose action is SIG_DFL, SIG_IGN, or SIG_HOLD as the calling process. However, if the action is to catch the signal, then the action is reset to SIG_DFL, and any pending signal for this type is held.

When any of these exec routines is called successfully and does not return, routines registered previously by atexit(S) will not be executed at the termination of the new process and must be registered again for the new process if they need to be executed at the termination of the new process.

If the set-user-ID mode bit of the new process file is set (see chmod(S)), exec sets the effective user ID of the new process to the owner ID of the new process file. Similarly, if the set-group-ID mode bit of the new process file is set, the effective group ID of the new process is set to the group ID of the new process file. The real user ID and real group ID of the new process remain the same as those of the calling process.

The shared memory segments attached to the calling process are not attached to the new process; see shmop(S).

At the startup of the new process, LC_ALL is set to a null string:

setlocale(LC_ALL, "");

and consequently, all internationalization variables starting with LC_ and the variable LANG have the value for the system configured default locale. See locale(M) for how to set a system default locale. In the XPG4 environment (and in the XPG4 environment only), LC_ALL is set to "C" at startup:

setlocale(LC_ALL, "C");

Consequently, for the XPG4 environment, variables starting with LC_ and the variable LANG have the value ``C''.

Profiling is disabled for the new process; see profil(S).

The new process also inherits the following attributes from the calling process:

nice value; see nice(S)
process ID
parent process ID
process group ID
semadj values; see semop(S)
tty group ID; see exit(S), sigaction(S), signal(M), and signal(S)
trace flag; see ptrace(S) request 0
time left until an alarm clock signal; see alarm(S)
current working directory
root directory
file mode creation mask; see umask(S)
file size limit; see ulimit(S)
utime, stime, cutime, and cstime; see times(S)
file-locks; see fcntl(S) and lockf(S)

Return values

If exec returns to the calling process, an error has occurred; the return value is -1 and errno is set to indicate the error.

Diagnostics

The exec system call fails and returns to the calling process if one or more of the following is true:

[E2BIG]

The number of bytes in the new process's argument list is greater than the system-imposed limit of 5120 bytes.

[EACCES]

Search permission is denied for a directory listed in the new process file's path prefix.
The new process file is not an ordinary file.
The new process file mode denies execution permission.

[EAGAIN]

Not enough memory.

[EFAULT]

Required hardware is not present.
path, argv, or envp point to an illegal address.

[EINTR]

A signal was caught during the exec system call.

[ELIBACC]

Required shared library does not have execute permission.

[ELIBEXEC]

Trying to exec a shared library directly.

[EMULTIHOP]

Components of path require hopping to multiple remote machines.

[ENAMETOOLONG]

The pathname in path, or in file, or an element in the environmental variable PATH is longer than PATH_MAX. This error also occurs when a pathname component is longer than NAME_MAX.

[ENOENT]

One or more components of the new process path name of the file do not exist.

[ENOEXEC]

The exec is not an execlp or execvp, and the new process file has the appropriate access permission but an invalid magic number in its header.

[ENOLINK]

path points to a remote machine and the link to that machine is no longer active.

[ENOMEM]

The new process requires more memory than is allowed by the system-imposed maximum MAXMEM.

[ENOTDIR]

A component of the new process path of the file prefix is not a directory.

[ETXTBSY]

The new process file is a pure procedure (shared text) file that is currently open for writing by some process.

Notes

Security services provided by the operating system provide the following:

Executing a setuid/setgid file without a valid login UID fails.
The login UID is inherited from the parent process.

Standards conformance

execl, execle, execlp, execv, execve, execvp and environ are conformant with:

X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .