EXECL(3)						     Library Functions 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 execve system call.  Refer to execve(2) 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  name  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 char-
       acter  strings  constituting the file and the arguments; the first argument is conventionally the same as the file name (or its last compo-
       nent).  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  exe-
       cuted and a vector of strings containing the arguments.	The last argument string must be followed by a 0 pointer.

       The  exect  version  is	used  when  the  executed file is to be manipulated with ptrace(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 setting the trace bit in  the  process
       status longword.  Exect is not available on the PDP-11.

       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 convention-
       ally 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(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 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.

FILES

       /bin/sh	shell, invoked if command file found by execlp or execvp

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

4.2 Berkeley Distribution					  August 4, 1987							  EXECL(3)