Commit | Line | Data |
---|---|---|
b49c82da C |
1 | .TH EXECL 3 "1 April 1981" |
2 | .UC 4 | |
3 | .SH NAME | |
4 | execl, execv, execle, execlp, execvp, exec, exece, exect, environ \- execute a file | |
5 | .SH SYNOPSIS | |
6 | .nf | |
7 | .B execl(name, arg0, arg1, ..., argn, 0) | |
8 | .B char *name, *arg0, *arg1, ..., *argn; | |
9 | .PP | |
10 | .B execv(name, argv) | |
11 | .B char *name, *argv[]; | |
12 | .PP | |
13 | .B "execle(name, arg0, arg1, ..., argn, 0, envp)" | |
14 | .B "char *name, *arg0, *arg1, ..., *argn, *envp[];" | |
15 | .PP | |
16 | .B "exect(name, argv, envp) | |
17 | .B "char *name, *argv[], *envp[]; | |
18 | .PP | |
19 | .B extern char **environ; | |
20 | .fi | |
21 | .SH DESCRIPTION | |
22 | These routines provide various interfaces to the | |
23 | .I execve | |
24 | system call. Refer to | |
25 | .IR execve (2) | |
26 | for a description of their properties; only | |
27 | brief descriptions are provided here. | |
28 | .PP | |
29 | .I Exec | |
30 | in all its forms | |
31 | overlays the calling process with the named file, then | |
32 | transfers to the | |
33 | entry point of the core image of the file. | |
34 | There can be no return from a successful exec; the calling | |
35 | core image is lost. | |
36 | .PP | |
37 | The | |
38 | .I name | |
39 | argument | |
40 | is a pointer to the name of the file | |
41 | to be executed. | |
42 | The pointers | |
43 | .IR arg [ 0 ], | |
44 | .IR arg [ 1 "] ..." | |
45 | address null-terminated strings. | |
46 | Conventionally | |
47 | .IR arg [ 0 ] | |
48 | is the name of the | |
49 | file. | |
50 | .PP | |
51 | Two interfaces are available. | |
52 | .I execl | |
53 | is useful when a known file with known arguments is | |
54 | being called; | |
55 | the arguments to | |
56 | .I execl | |
57 | are the character strings | |
58 | constituting the file and the arguments; | |
59 | the first argument is conventionally | |
60 | the same as the file name (or its last component). | |
61 | A 0 argument must end the argument list. | |
62 | .PP | |
63 | The | |
64 | .I execv | |
65 | version is useful when the number of arguments is unknown | |
66 | in advance; | |
67 | the arguments to | |
68 | .I execv | |
69 | are the name of the file to be | |
70 | executed and a vector of strings containing | |
71 | the arguments. | |
72 | The last argument string must be followed | |
73 | by a 0 pointer. | |
74 | .PP | |
75 | The | |
76 | .I exect | |
77 | version is used when the executed file is to be | |
78 | manipulated with | |
79 | .IR ptrace (2). | |
80 | The program is forced to single step a single | |
81 | instruction giving the parent an opportunity to | |
82 | manipulate its state. On the VAX-11 this is done | |
83 | by setting the trace bit in the process status | |
84 | longword. | |
85 | .PP | |
86 | When a C program is executed, | |
87 | it is called as follows: | |
88 | .PP | |
89 | .nf | |
90 | main(argc, argv, envp) | |
91 | int argc; | |
92 | char **argv, **envp; | |
93 | .fi | |
94 | .PP | |
95 | where | |
96 | .I argc | |
97 | is the argument count | |
98 | and | |
99 | .I argv | |
100 | is an array of character pointers | |
101 | to the arguments themselves. | |
102 | As indicated, | |
103 | .I argc | |
104 | is conventionally at least one | |
105 | and the first member of the array points to a | |
106 | string containing the name of the file. | |
107 | .PP | |
108 | .I Argv | |
109 | is directly usable in another | |
110 | .I execv | |
111 | because | |
112 | .IR argv [ argc ] | |
113 | is 0. | |
114 | .PP | |
115 | .I Envp | |
116 | is a pointer to an array of strings that constitute | |
117 | the | |
118 | .I environment | |
119 | of the process. | |
120 | Each string consists of a name, an \*(lq=\*(rq, and a null-terminated value. | |
121 | The array of pointers is terminated by a null pointer. | |
122 | The shell | |
123 | .IR sh (1) | |
124 | passes an environment entry for each global shell variable | |
125 | defined when the program is called. | |
126 | See | |
127 | .IR environ (7) | |
128 | for some conventionally | |
129 | used names. | |
130 | The C run-time start-off routine places a copy of | |
131 | .I envp | |
132 | in the global cell | |
133 | .IR environ , | |
134 | which is used | |
135 | by | |
136 | .I execv | |
137 | and | |
138 | .I execl | |
139 | to pass the environment to any subprograms executed by the | |
140 | current program. | |
141 | .PP | |
142 | .I Execlp | |
143 | and | |
144 | .I execvp | |
145 | are called with the same arguments as | |
146 | .I execl | |
147 | and | |
148 | .IR execv , | |
149 | but duplicate the shell's actions in searching for an executable | |
150 | file in a list of directories. | |
151 | The directory list is obtained from the environment. | |
152 | .SH FILES | |
153 | .ta \w'/bin/sh 'u | |
154 | /bin/sh shell, invoked if command file found | |
155 | by | |
156 | .I execlp | |
157 | or | |
158 | .I execvp | |
159 | .SH "SEE ALSO" | |
160 | execve(2), | |
161 | fork(2), | |
162 | environ(7), | |
163 | csh(1) | |
164 | .SH DIAGNOSTICS | |
165 | If the file cannot be found, | |
166 | if it is not executable, | |
167 | if it does not start with a valid magic number (see | |
168 | .IR a.out (5)), | |
169 | if maximum memory is exceeded, | |
170 | or if the arguments require too much space, | |
171 | a return | |
172 | constitutes the diagnostic; | |
173 | the return value is \-1. | |
174 | Even for the super-user, | |
175 | at least one of the execute-permission bits must be set for | |
176 | a file to be executed. | |
177 | .SH BUGS | |
178 | If | |
179 | .I execvp | |
180 | is called to execute a file that turns out to be a shell | |
181 | command file, | |
182 | and if it is impossible to execute the shell, | |
183 | the values of | |
184 | .I argv[0] | |
185 | and | |
186 | .I argv[\-1] | |
187 | will be modified before return. |