4.3BSD - /usr/man/cat3/execve.0

EXECL(3)                                                              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.  Con‐
       ventionally 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 charac‐
       ter 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  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.

       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 instruc‐
       tion 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.

       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 conven‐
       tionally 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 environ���
       ment 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  consti‐
       tutes 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 com‐
       mand 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       April 25, 1986                        EXECL(3)