./_Man_SunOS_4.1.3_html/html3/execv.3v.html

Manual page for EXECL(3V)

execl, execv, execle, execlp, execvp - execute a file

SYNOPSIS

int execl(path, arg0 [ , arg1,... , argn ] (char *)0)

char *path, *arg0, *arg1, ..., *argn;

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

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

char *path, *arg0, *arg1, ..., *argn, *envp[ ];

int execlp(file, arg0 [ , arg1,... , argn ] (char *)0)

char *file, *arg0, *arg1, ..., *argn;

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

extern char **environ;

DESCRIPTION

These routines provide various interfaces to the execve() system call. Refer to execve.2v for a description of their properties; only brief descriptions are provided here.

exec() 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.

The filename 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.

Two interfaces are available. 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 (char *)0 argument must end the argument list. The cast to type char * insures portability.

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.

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

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

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.

envp is a pointer to an array of strings that constitute the environment of the process. 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.5v 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() and execl() to pass the environment to any subprograms executed by the current program.

execlp() and execvp() are called with the same arguments as execl() and execv(), but duplicate the shell's actions in searching for an executable file in a list of directories. The directory list is obtained from the environment.

RETURN VALUES

These functions return to the calling process only on failure. They return -1 and set errno to indicate the error if path or 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. Even for the super-user, at least one of the execute-permission bits must be set for a file to be executed.

ERRORS

If any of the following conditions occur, these functions will return and set errno to one of the following:

E2BIG: The number of bytes used by the new process image's argument list and environment list is greater than {ARG_MAX} bytes (see sysconf.2v
EACCES: Search permission is denied for a directory listed in the new process image file's path prefix.
: The new process image file denies execution permission.
: The new process image file is not a regular file.
ENAMETOOLONG: The length of the path or file, or an element of the environment variable PATH prefixed to a file, exceeds {PATH_MAX}.
: A pathname component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect for that file (see pathconf.2v
ENOENT: One or more components of the new process image file's pathname do not exist.
ENOTDIR: A component of the new process image file's path prefix is not a directory.

if the following condition occurs, execl(), execv(), and execle() set errno to:

ENOEXEC: The new process image file has the appropriate access permission, but is not in the proper format.

If the following condition is detected, the exec functions set errno to:

ENOMEM: The new process image requires more memory than there is swap space available.
: On Sun-3 systems, the new process image requires more than 231 bytes.

SYSTEM V ERRORS

In addition to the above, if the following condition occurs, the exec functions set errno to:

ENOENT: path or file points to a null pathname.

FILES

/usr/bin/sh: shell, invoked if command file found by execlp() or execvp()