4.3BSD-UWisc/man/cat3/execl.3

EXECL(3)            UNIX Programmer's Manual             EXECL(3)



NAME
     execl, execv, execle, execlp, execvp, exec, execve, exect,
     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[];

     exect(name, argv, envp)
     char *name, *argv[], *envp[];

     extern char **environ;

DESCRIPTION
     These routines provide various interfaces to the _e_x_e_c_v_e sys-
     tem call.  Refer to _e_x_e_c_v_e(2) for a description of their
     properties; only brief descriptions are provided here.

     _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.

     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.

     Two interfaces are available.  _e_x_e_c_l is useful when a known
     file with known arguments is being called; the arguments 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
     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 _e_x_e_c_t version is used when the executed file is to be
     manipulated with _p_t_r_a_c_e(2).  The program is forced to single
     step a single instruction giving the parent an opportunity
     to manipulate its state.  On the VAX-11 this is done by set-
     ting the trace bit in the process status longword.



Printed 12/27/86         April 25, 1986                         1






EXECL(3)            UNIX Programmer's Manual             EXECL(3)



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

     _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.

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
     execve(2), fork(2), environ(7), csh(1)

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.



Printed 12/27/86         April 25, 1986                         2