EXECL(3)EXECL(3)NAME
execl, execv, execle, execlp, execvp, environ - execute a file
SYNOPSIS
int execl(const char *name, const char *arg0, const char *arg1, ...,
const char *argn, (char *) 0);
int execv(const char *path, const char *argv[]);
int execle(const char *path, const char *arg0, const char *arg1, ...,
const char *argn, (char *) 0, const char *envp[]);
int execlp(const char *file, const char *arg0, const char *arg1, ...,
const char *argn, (char *) 0);
int execvp(const char *file, const char *argv[]);
extern char **environ;
DESCRIPTION
These routines provide various interfaces to the execve(2) and execv(2)
system calls. Refer to execve(2) or execv(2) for a description of
their properties; only brief descriptions are provided here.
The exec family of functions in all its forms overlays the calling
process with the named file, then transfers to the entry point of the
core image of the file. There can be no return from a successful exec;
the calling core image is lost. An unsuccessful exec generates a
return value of -1.
The path argument is a pointer to the name of the file to be executed.
The pointers arg[0], arg[1]... address null-terminated strings.
Conventionally arg[0] is the name of the file.
Execl is useful when a known file with known arguments is being called;
the arguments to execl are the character strings constituting the file
and the arguments; the first argument is conventionally the same as the
file name (or its last component). A 0 argument must end the argument
list.
The execv version is useful when the number of arguments is unknown in
advance; the arguments to execv are the name of the file to be executed
and a vector of strings containing the arguments. The last argument
string must be followed by a 0 pointer.
The execlp and execvp interfaces take the argument file that is 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 this file. Otherwise, the path prefix for this
file is obtained by a search of the directories passed as the
environment variable PATH. If this environment variable is not
present, then the directories /bin and /usr/bin are searched.
When a C program is executed, it is called as follows:
main(int argc, char *argv[]);
where argc is the argument count and argv is an array of character
pointers to the arguments themselves. 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.
Argv is directly usable in another execv because argv[argc] is 0.
Additionally, the following variable:
extern char **environ;
is initialized as a pointer to an array of character pointers to the
environment strings. Each string consists of a name, an “=”, and a
null-terminated value. The array of pointers is terminated by a null
pointer. The shell sh(1) passes an environment entry for each global
shell variable defined when the program is called. See environ(7) for
some conventionally used names. The C run-time start-off routine
places a copy of envp in the global cell environ, which is used by
execv(2) and execl(2) to pass the environment to any subprograms
executed by the current program.
FILES
/bin/sh shell, invoked if command file found by execlp or execvp
ERRORS
The following errors may occur:
[E2BIG] The number of bytes used by the argument list and the
environment list of the new process image is greater
than the system-imposed limit of {ARG_MAX} bytes.
[EACCES] Search permission is denied for a directory listed in
the path prefix of the new processes image file, or the
new process image file denies execution permission, or
the new process image file is not a regular file.
[ENAMETOOLONG] A pathname component exceeds 255 characters; or,
pathname or file, or an element of the environment
variable PATH prefixed to file, exceeds 1023 characters.
For POSIX applications these values are given by the
constants {NAME_MAX} and {PATH_MAX}, respectively.
[ENOENT] One or more components of the pathname of the new
process image file do not exist, or the path or file
argument points to an empty string.
[ENOTDIR] A component of the path prefix of the new process image
file is not a directory.
[ENOEXEC] The new process image file has the appropriate access
permission, but is not in the proper format.
DIAGNOSTICS
If the file cannot be found, if it is not executable, if it does not
start with a valid magic number (see a.out(5)), if maximum memory is
exceeded, or if the arguments require too much space, a return
constitutes the diagnostic; the return value is -1. Even for the
super-user, at least one of the execute-permission bits must be set for
a file to be executed.
BUGS
If execvp is called to execute a file that turns out to be a shell
command file, and if it is impossible to execute the shell, the values
of argv[0] and argv[-1] will be modified before return.
SEE ALSOexecve(2), fork(2), getenv(3), environ(7), csh(1)
August 1, 1992 EXECL(3)