NAME
environ, execl, execv, execle, execve, execlp, execvp - Exe-
cutes a file
LIBRARY
Standard C Library (libc.a): execlp(), execvp()
SYNOPSIS
#include <unistd.h>
extern char **environ;
int execl (
const char *path,
const char *arg,
... );
int execv (
const char *path,
char * const argv[ ] );
int execle (
const char *path,
const char *arg,
...
char * const envp[ ] );
int execve (
const char *path,
char * const argv[ ],
char * const envp[ ] );
int execlp (
const char *file,
const char *arg,
... );
int execvp (
const char *file,
char * const argv[ ] );
PARAMETERS
path Points to a pathname identifying the new process
image file.
arg Specifies a pointer to a null-terminated string.
argv Specifies an array of character pointers to null-
terminated strings.
envp Specifies an array of character pointers to null-
terminated strings, constituting the environment
for the new process.
file Identifies the new process image file.
DESCRIPTION
The exec functions replace the current process image with a
new process image. The new image is constructed from a reg-
ular executable file, called a new process image file. A
successful exec does not return, because the calling process
image is overlaid by the new process image.
When a program is executed as a result of an exec call, it
is entered as a function call as follows:
int main (
int argc,
char *argv[ ] );
Here, argc is the argument count and argv[ ] is an array of
character pointers to the arguments themselves. In addi-
tion, the following variable is initialized as a pointer to
an array of character pointers to the environment strings:
extern char **environ;
The argv and environ arrays are each terminated by a null
pointer. The null pointer terminating the argv array is not
counted in argc.
The arguments specified by a program with one of the exec
functions are passed on to the new process image in the
corresponding arguments to main().
The path argument points to a pathname that identifies the
new process image file.
The file argument is used to construct a pathname that iden-
tifies the new process image file. If the file argument
contains a slash character, the file argument is used as the
pathname for this file. Otherwise, the path prefix for this
file is obtained by a search of the directories passed as
the PATH environment variable.
The new process image file is formatted as an executable
text or binary file, in one of the formats recognized by the
exec functions. An executable text file is identified by a
header line with the following syntax:
#! interpreter_name [ optional_string ]
The #! identifies the file as an executable text file. The
new process image is constructed from the process image file
named by the interpreter_name string. The arguments are
modified as follows:
o argv[0] is set to the name of the interpreter.
o If the optional_string is present, argv[1] is set to
the optional_string.
o The next element of argv[] is set to the original value
of path.
o The remaining elements of argv[] are set to the origi-
nal elements of argv[], starting at argv[1]. The ori-
ginal argv[0] is discarded.
An executable binary file can be loaded either directly by
the exec function, or indirectly by the program loader. The
exec function chooses to use direct or indirect loading
based on the contents of the new process image file. For
example, indirect loading is used if the new process image
file has unresolved symbols, requiring use of a shared
library.
When indirect loading is used, the new process image is con-
structed from the default program loader, /sbin/loader, in
the same manner as described for the exec_with_loader()
function. The default program loader is then responsible
for completing the new program image by loading the new pro-
cess image file and any shared libraries on which it
depends.
If the process image file is not a valid executable object,
the execlp() and execvp() functions use the contents of that
file as standard input to a command interpreter conforming
to the system() function. In this case, the command inter-
preter becomes the new process image.
The argv argument is an array of character pointers to
null-terminated strings. 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]
should point to a filename that is associated with the pro-
cess being started by one of the exec functions.
The const char *arg and subsequent ellipses in the execl(),
execlp(), and execle() functions can be thought of as arg0,
arg1, ..., argn. Together they describe a list of one or
more pointers to null-terminated character strings that
represent the argument list available to the new program.
The first argument must point to a filename that is associ-
ated with the process being started by one of the exec func-
tions, and the last argument must be a null pointer. For
the execle() function, the environment is provided by fol-
lowing the null pointer that will terminate the list of
arguments in the parameter list to execle() with an addi-
tional parameter as if it were declared as:
char * const envp[]
The envp argument to execve(), and the final argument to
execle(), name an array of character pointers to null-
terminated strings. These strings constitute the environ-
ment for the new process image. The environment array is
terminated with a null pointer.
For those forms not containing an envp pointer (execl(),
execv(), execlp() and execvp()) the environment for the new
process image is taken from the external variable environ in
the calling process.
The number of bytes available for the new process' combined
argument and environment lists is ARG_MAX. ARG_MAX includes
the null terminators on the strings; it does not include
the pointers.
File descriptors open in the calling process image remain
open in the new process image, except for those whose
close-on-exec flag FD_CLOEXEC is set (see the fcntl() func-
tion). For those file descriptors that remain open, all
attributes of the open file description, including file
locks, remain unchanged.
The state of directory streams and message catalog descrip-
tors in the new process image is undefined.
Each mapped file and shared memory region created with the
mmap() function is unmapped by a successful call to any of
the exec functions, except those regions mapped with the
MAP_INHERIT option. Regions mapped with the MAP_INHERIT
option remain mapped in the new process image.
Signals set to the default action (SIG_DFL) in the calling
process image are set to the default action in the new pro-
cess image. Signals set to be ignored (SIG_IGN) by the cal-
ling process image are set to be 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
(see the signal.h header file).
If the set user ID mode bit of the new process image file is
set (see the chmod() function), the effective user ID of the
new process image is set to the owner ID of the new process
image file. Similarly, if the set group ID mode bit of the
new process image file is set, the effective group ID of the
new process image is set to the group ID of the new process
image file. The real user ID, real group ID, and supplemen-
tary group IDs of the new process image remain the same as
those of the calling process image. 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) for
use by the setuid() function.
The following attributes of the calling process image are
unchanged after successful completion of any of the exec
functions:
o Process ID
o Parent process ID
o Process group ID
o Session membership
o Real user ID
o Real group ID
o Supplementary group IDs
o Time left until an alarm clock signal (see the alarm()
function)
o Current working directory
o Root directory
o File mode creation mask (see the umask() function)
o Process signal mask (see the sigprocmask() function)
o Pending signals (see the sigpending() function)
o The tms_utime, tms_stime, tms_cutime, and tms_cstime
fields of the tms structure.
o File size limit (see the ulimit() function)
o Nice value (see the nice() function)
Upon successful completion, the exec functions mark for
update the st_atime field of the file.
NOTES
AES Support Level:
Full use
RETURN VALUE
If one of the exec functions returns to the calling process
image, an error has occurred; the return value is -1, and
errno is set to indicate the error.
ERRORS
If the exec functions fail, errno may be set to one of the
following values:
[E2BIG] The number of bytes used by the new process
image's argument list and environment list is
greater than the system-imposed limit of ARG_MAX
bytes.
[EACCES] Search permission is denied for a directory listed
in the new process image file's path prefix, or
the new process image file denies execution per-
mission, or the new process image file is not a
regular file and the implementation does not sup-
port execution of files of its type.
[ENAMETOOLONG]
The length of the path or file arguments, or an
element of the environment variable PATH prefixed
to a file, exceeds PATH_MAX, or a pathname com-
ponent is longer than NAME_MAX and _POSIX_NO_TRUNC
is in effect for that file.
[ENOENT] One or more components of the new process image
file's pathname do not exist, or the path or file
argument points to an empty string.
[ENOTDIR] A component of the new process image file's path
prefix is not a directory.
[EFAULT] The path argument is an invalid address.
[ELOOP] Too many symbolic links were encountered in path-
name resolution.
[ENOMEM] Insufficient memory is available.
If the execl(), execv(), execle(), or execve() function
fails, errno may be set to the following value:
[ENOEXEC] The new process image file has the appropriate
access permission but is not in the proper format.
RELATED INFORMATION
Functions: alarm(3), exit(2), fcntl(2), fork(2), getenv(3),
nice(3), putenv(3), sigaction(2), system(3), times(3),
ulimit(3), umask(2), mmap(2), exec_with_loader(2)
Acknowledgement and Disclaimer