exec(2)

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

Synopsis

   #include <unistd.h>
   
   int execl (const char path, const char arg0, .../*,
   	const char argn, (char *)0*/);
   

   int execv (const char path, char const argv);
   

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

   int execve (const char path, char const argv,
   	char const envp);
   

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

   int execvp (const char file, char const argv);

Description

exec in all its forms overlays a new process image on an old process. The new process image is constructed from an ordinary executable file. This file is either an executable object file or a file of data for an interpreter. There can be no return from a successful exec because the calling process image is overlaid by the new process image.

An interpreter file begins with a line of the form

   #! pathname [arg]

where pathname is the path of the interpreter, and arg is an optional argument. When you exec an interpreter file, the system execs the specified interpreter. The pathname specified in the interpreter file is passed as arg0 to the interpreter. If arg was specified in the interpreter file, it is passed as arg1 to the interpreter. The remaining arguments to the interpreter are arg0 through argn of the originally executed file.

When a C program is executed, it is called as follows:

   int main (int argc, char argv[], char 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 null-terminated strings that constitute the environment for the new process. The value of the argument argc is conventionally at least one. The initial member of the array argv points to a string containing the name of the file.

The argument path points to a pathname that identifies the new process file. For execlp and execvp, the argument file points to the new process file. If the file argument does not contain a slash character, the path prefix for this file is obtained by searching the directories passed as the environment variable PATH [see environ(5)]. The environment is supplied typically by the shell [see sh(1)].

If the new executable file is not an executable object file and not an interpreter file, execlp and execvp use the contents of that file as standard input to the user's default shell.

The arguments arg0, ... are pointers to null-terminated character strings. These strings constitute the argument list available to the new process. The list is terminated by a null pointer. By convention, at least arg0 is present and points to a string that is the same as file or path (or its last component), point to null-terminated character strings. It will become the name of the process, as displayed by the ps command. The list of argument strings is terminated by a (char )0 argument.

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[0] must have at least one member, and it should point to a string that is the same as file or path (or its last component). argv is terminated by a null pointer.

The argument envp is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process. A null pointer terminates envp. For execl, execv, execvp, and execlp, the C run-time start-off routine places a pointer to the environment of the calling process in the global object extern char environ, and it is used to pass the environment of the calling process to the new process image.

File descriptors open in the calling process remain open in the new process image, except for those whose ``close-on-exec'' flag is set [see fcntl(2)]. For those file descriptors that remain open, the file pointer remains unchanged and all file locks associated with the file are preserved.

Signals being caught by the calling process are set to the default disposition in the new process image [see signal(2)]. Otherwise, the new process image inherits the signal dispositions of the calling process.

If the set-user-ID-on-execution mode bit of the new process file is set, the exec routines set the effective user ID of the new process to the owner ID of the new process file [see chmod(2)]. 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, real group ID and supplementary group IDs of the new process remain the same as those of the calling process. The saved user and group IDs of the new process image are set to the effective user and group IDs of the calling process. Set-user-ID and set-group-ID on execution shall occur for interpreter files.

If the calling process has the P_SYSOPS privilege, the set-user-ID and set-group-ID bits are honored when the process is being controlled by ptrace; otherwise, they are not honored by ptrace.

The shared memory segments attached to the calling process will not be attached to the new process image [see shmop(2)].

Profiling is disabled for the new process image [see profil(2)].

The new process image also preserves the following attributes across this system call.

nice value: [see nice(2)] scheduler class and priority [see priocntl(2)]
process ID
parent process ID
process group ID
supplementary group ID
semadj values: [see semop(2)]
session ID: [see exit(2) and signal(2)]
trace flag: [see ptrace(2) request 0]
time left until an alarm clock signal: [see alarm(2)]
current directory
root directory
file mode creation mask: [see umask(2)]
resource limits: [see getrlimit(2)]
utime, stime, cutime, and cstime: [see times(2)]
file-locks: [see fcntl(2) and lockf(3C)]
controlling terminal
process signal mask: [see sigprocmask(2)]
pending signals: [see sigpending(2)]

If exec succeeds, it marks for update the st_atime field of the file.

If exec succeeds, an internal reference to the process image file is created. This reference is removed some time later, but not later than process termination or successful completion of a subsequent call to one of the exec functions.

Return values

On success, exec overlays the calling process image with the new process image and there is no return to the calling process. If exec fails while it can still return to the calling process, it returns -1 and sets errno to identify the error. If exec fails after a point of no return to the calling process, the calling process is sent a SIGKILL signal. This can occur during startup, under certain resource depletion conditions. For example, it can occur if the system is running out of swap space, or if there are problems with the exec header, shared libraries, or dynamic libraries.

Errors

If exec returns to the calling LWP, an error has occurred. In this event, no side effect is suffered. That is, neither the calling LWP nor the other LWPs in the process are terminated. In the following conditions, exec fails and sets errno to:

EACCES: Search permission is denied for a directory listed in the new executable file's path prefix.
EACCES: The new executable file is not an ordinary file.
EACCES: Execute permission on the new executable file is denied.
E2BIG: The number of bytes in the argument list of the new process image is greater than the system-imposed limit of {ARG_MAX} bytes. The argument list limit is sum of the size of the argument list plus the size of the environment's exported shell variables.
EAGAIN: Total amount of system memory available when reading via raw I/O is temporarily insufficient.
EFAULT: Required hardware is not present.
EFAULT: An argument points to an illegal address.
EINTR: A signal was caught during the exec system call.
ELIBACC: A required shared library does not have execute permission.
ELIBEXEC: Trying to exec a shared library directly.
ELOOP: Too many symbolic links were encountered in translating path or file.
EMULTIHOP: Components of path require hopping to multiple remote machines and the file system type does not allow it.
ENAMETOOLONG: The length of the file or path argument exceeds {PATH_MAX}, or the length of a file or path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.
ENOENT: One or more components of the pathname of the executable file do not exist, or path or file points to an empty string.
ENOLOAD: Failure in loading a loadable exec module.
ENOTDIR: A component of the pathname of the executable file is not a directory.
ENOEXEC: The exec is not an execlp or execvp, and the new executable file has the appropriate access permission but an invalid magic number in its header.
ENOMEM: The new process image requires more memory than allowed by RLIMIT_VMEM [see getrlimit(2).
ENOLINK: path points to a remote machine and the link to that machine is no longer active.

References

a.out(4), alarm(2), environ(5), exit(2), fcntl(2), fork(2), getrlimit(2), lockf(3C), nice(2), priocntl(2), ps(1), ptrace(2), semop(2), sh(1), signal(2), sigpending(2), sigprocmask(2), system(3S), times(2), umask(2)

Notices

Considerations for threads programming

A successful exec will effectively terminate all but one thread of a multithreaded process. The process starts the new program with a single multiplexed (that is, not bound) thread. In the case of failure and return of an error condition to the calling thread, sibling threads are not affected.

Considerations for lightweight processes

The process starts the new program with a single LWP. In general, the LWPID number of that single LWP need not be that of the LWP of the calling thread; however, if the process is being accessed via /proc (that is, being debugged) the LWPID is preserved across the exec system call.