1EXECL(3)                   Library Functions Manual                   EXECL(3)
2
3
4

NAME

6       execl,  execv,  execle,  execlp, execvp, exec, execve, exect, environ -
7       execute a file
8

SYNOPSIS

10       execl(name, arg0, arg1, ..., argn, 0)
11       char *name, *arg0, *arg1, ..., *argn;
12
13       execv(name, argv)
14       char *name, *argv[];
15
16       execle(name, arg0, arg1, ..., argn, 0, envp)
17       char *name, *arg0, *arg1, ..., *argn, *envp[];
18
19       exect(name, argv, envp)
20       char *name, *argv[], *envp[];
21
22       extern char **environ;
23

DESCRIPTION

25       These routines provide various interfaces to the  execve  system  call.
26       Refer  to  execve(2)  for a description of their properties; only brief
27       descriptions are provided here.
28
29       Exec in all its forms overlays the calling process with the named file,
30       then transfers to the entry point of the core image of the file.  There
31       can be no return from a successful exec;  the  calling  core  image  is
32       lost.
33
34       The  name argument is a pointer to the name of the file to be executed.
35       The pointers arg[0], arg[1] ...  address null-terminated strings.  Con‐
36       ventionally arg[0] is the name of the file.
37
38       Two  interfaces  are available.  execl is useful when a known file with
39       known arguments is being called; the arguments to execl are the charac‐
40       ter strings constituting the file and the arguments; the first argument
41       is conventionally the same as the file name (or its last component).  A
42       0 argument must end the argument list.
43
44       The  execv version is useful when the number of arguments is unknown in
45       advance; the arguments to execv are the name of the file to be executed
46       and  a  vector  of strings containing the arguments.  The last argument
47       string must be followed by a 0 pointer.
48
49       The exect version is used when the executed file is to  be  manipulated
50       with ptrace(2).  The program is forced to single step a single instruc‐
51       tion giving the parent an opportunity to manipulate its state.  On  the
52       VAX-11  this  is  done  by  setting the trace bit in the process status
53       longword.  Exect is not available on the PDP-11.
54
55       When a C program is executed, it is called as follows:
56
57            main(argc, argv, envp)
58            int argc;
59            char **argv, **envp;
60
61       where argc is the argument count and argv  is  an  array  of  character
62       pointers  to  the  arguments themselves.  As indicated, argc is conven‐
63       tionally at least one and the first member of the  array  points  to  a
64       string containing the name of the file.
65
66       Argv is directly usable in another execv because argv[argc] is 0.
67
68       Envp  is  a pointer to an array of strings that constitute the environ‐
69       ment of the process.  Each string consists of a name,  an  “=”,  and  a
70       null-terminated  value.   The array of pointers is terminated by a null
71       pointer.  The shell sh(1) passes an environment entry for  each  global
72       shell  variable defined when the program is called.  See environ(7) for
73       some conventionally used  names.   The  C  run-time  start-off  routine
74       places  a  copy  of  envp  in the global cell environ, which is used by
75       execv and execl to pass the environment to any subprograms executed  by
76       the current program.
77
78       Execlp  and  execvp  are  called  with  the same arguments as execl and
79       execv, but duplicate the shell's actions in searching for an executable
80       file in a list of directories.  The directory list is obtained from the
81       environment.
82

FILES

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

SEE ALSO

87       execve(2), fork(2), environ(7), csh(1)
88

DIAGNOSTICS

90       If the file cannot be found, if it is not executable, if  it  does  not
91       start  with  a  valid magic number (see a.out(5)), if maximum memory is
92       exceeded, or if the arguments require too much space, a return  consti‐
93       tutes the diagnostic; the return value is -1.  Even for the super-user,
94       at least one of the execute-permission bits must be set for a  file  to
95       be executed.
96

BUGS

98       If execvp is called to execute a file that turns out to be a shell com‐
99       mand file, and if it is impossible to execute the shell, the values  of
100       argv[0] and argv[-1] will be modified before return.
101
102
103
1044.2 Berkeley Distribution       August 4, 1987                        EXECL(3)
Impressum