2.9BSD/usr/man/cat2/exec.2
EXEC(2) UNIX Programmer's Manual EXEC(2)
NAME
execl, execv, execle, execve, execlp, execvp, exec, exece,
environ - execute a file
SYNOPSIS
execl(name, arg0, arg1, ..., argn, 0)
char *name, *arg0, *arg1, ..., *argn;
execv(name, argv)
char *name, *argv[];
execle(name, arg0, arg1, ..., argn, 0, envp)
char *name, *arg0, *arg1, ..., *argn, *envp[];
execve(name, argv, envp)
char *name, *argv[], *envp[];
extern char **environ;
DESCRIPTION
_E_x_e_c 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.
Files remain open across _e_x_e_c unless explicit arrangement
has been made; see _i_o_c_t_l(2). Ignored/held signals remain
ignored/held across these calls, but signals that are caught
(see _s_i_g_n_a_l(2)) are reset to their default values.
Each user has a _r_e_a_l user ID and group ID and an _e_f_f_e_c_t_i_v_e
user ID and group ID. The real ID identifies the person
using the system; the effective ID determines his access
privileges. _E_x_e_c changes the effective user and group ID to
the owner of the executed file if the file has the `set-
user-ID' or `set-group-ID' modes. The real user ID is not
affected.
The _n_a_m_e argument is a pointer to the name of the file to be
executed. The pointers _a_r_g[_0], _a_r_g[_1] ... address null-
terminated strings. Conventionally _a_r_g[_0] is the name of
the file.
From C, two interfaces are available. _e_x_e_c_l is useful when
a known file with known arguments is being called; the argu-
ments to _e_x_e_c_l 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 _e_x_e_c_v version is useful when the number of arguments is
unknown in advance; the arguments to _e_x_e_c_v are the name of
Printed 4/7/83 4/1/81 1
EXEC(2) UNIX Programmer's Manual EXEC(2)
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 _a_r_g_c is the argument count and _a_r_g_v is an array of
character pointers to the arguments themselves. As indi-
cated, _a_r_g_c is conventionally at least one and the first
member of the array points to a string containing the name
of the file.
_A_r_g_v is directly usable in another _e_x_e_c_v because _a_r_g_v[_a_r_g_c]
is 0.
_E_n_v_p is a pointer to an array of strings that constitute the
_e_n_v_i_r_o_n_m_e_n_t 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 _s_h(1) passes an
environment entry for each global shell variable defined
when the program is called. See _e_n_v_i_r_o_n(5) for some conven-
tionally used names. The C run-time start-off routine
places a copy of _e_n_v_p in the global cell _e_n_v_i_r_o_n, which is
used by _e_x_e_c_v and _e_x_e_c_l to pass the environment to any sub-
programs executed by the current program. The _e_x_e_c routines
use lower-level routines as follows to pass an environment
explicitly:
execve(file, argv, environ);
execle(file, arg0, arg1, . . . , argn, 0, environ);
_E_x_e_c_l_p and _e_x_e_c_v_p are called with the same arguments as
_e_x_e_c_l and _e_x_e_c_v, 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. A sin-
gle parameter may be passed the interpreter, specified after
the name of the interpreter; its length and the length of
the name of the interpreter combined must not exceed 16
characters. The space (or tab) following the '#!' is manda-
tory, and the pathname must be explicit (no paths are
searched).
FILES
/bin/sh shell, invoked if command file found by _e_x_e_c_l_p or
_e_x_e_c_v_p
SEE ALSO
fork(2), environ(5), csh(1)
Printed 4/7/83 4/1/81 2
EXEC(2) UNIX Programmer's Manual EXEC(2)
DIAGNOSTICS
If the file cannot be found, if it is not executable, if it
does not start with a valid magic number (see _a._o_u_t(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 exe-
cuted.
BUGS
If _e_x_e_c_v_p 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 _a_r_g_v[_0] and _a_r_g_v[-_1] will be modified
before return.
ASSEMBLER (PDP-11)
(exec = 11.)
sys exec; name; argv
(exece = 59.)
sys exece; name; argv; envp
Plain _e_x_e_c is obsoleted by _e_x_e_c_e, but remains for historical
reasons.
When the called file starts execution on the PDP11, the
stack pointer points to a word containing the number of
arguments. Just above this number is a list of pointers to
the argument strings, followed by a null pointer, followed
by the pointers to the environment strings and then another
null pointer. The strings themselves follow; a 0 word is
left at the very top of memory.
sp-> nargs
arg0
...
argn
0
env0
...
envm
0
arg0: <arg0\0>
...
env0: <env0\0>
0
On the Interdata 8/32, the stack begins at a conventional
place (currently 0xD0000) and grows upwards. After _e_x_e_c,
the layout of data on the stack is as follows.
Printed 4/7/83 4/1/81 3
EXEC(2) UNIX Programmer's Manual EXEC(2)
int 0
arg0: byte ...
...
argp0: int arg0
...
int 0
envp0: int env0
...
int 0
%2-> space 40
int nargs
int argp0
int envp0
%3->
This arrangement happens to conform well to C calling con-
ventions.
On a VAX-11, the stack begins at 0x7ffff000 and grows
towards lower numbered addresses. After _e_x_e_c, the layout of
data on the stack is as follows.
ap ->
fp ->
sp -> .long nargs
.long arg0
...
.long argn
.long 0
.long env0
...
.long envn
.long 0
arg0: .byte "arg0\0"
...
envn: .byte "envn\0"
.long 0
Printed 4/7/83 4/1/81 4