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: ... env0: 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