Commit | Line | Data |
---|---|---|
11ed82bc BJ |
1 | .TH EXEC 2 |
2 | .SH NAME | |
3 | execl, execv, execle, execve, execlp, execvp, exec, exece, environ \- execute a file | |
4 | .SH SYNOPSIS | |
5 | .B execl(name, arg0, arg1, ..., argn, 0) | |
6 | .br | |
7 | .B char *name, *arg0, *arg1, ..., *argn; | |
8 | .PP | |
9 | .B execv(name, argv) | |
10 | .br | |
11 | .B char *name, *argv[ ]; | |
12 | .PP | |
13 | .B execle(name, arg0, arg1, ..., argn, 0, envp) | |
14 | .br | |
15 | .B char *name, *arg0, *arg1, ..., *argn, *envp[ ]; | |
16 | .PP | |
17 | .B execve(name, argv, envp); | |
18 | .br | |
19 | .B char *name, *argv[ ], *envp[ ]; | |
20 | .PP | |
21 | .B extern char **environ; | |
22 | .SH DESCRIPTION | |
23 | .I Exec | |
24 | in all its forms | |
25 | overlays the calling process with the named file, then | |
26 | transfers to the | |
27 | entry point of the core image of the file. | |
28 | There can be no return from a succussful exec; the calling | |
29 | core image is lost. | |
30 | .PP | |
31 | Files remain open across | |
32 | .I exec | |
33 | unless explicit arrangement has been made; | |
34 | see | |
35 | .IR ioctl (2). | |
36 | Ignored signals remain ignored across | |
37 | these calls, but | |
38 | signals that are caught (see | |
39 | .IR signal (2)) | |
40 | are reset | |
41 | to their default values. | |
42 | .PP | |
43 | Each user has a | |
44 | .I real | |
45 | user ID and group ID and an | |
46 | .I effective | |
47 | user ID and group ID. | |
48 | The | |
49 | real | |
50 | ID | |
51 | identifies the person using the system; | |
52 | the | |
53 | effective | |
54 | ID | |
55 | determines his access privileges. | |
56 | .I Exec | |
57 | changes the effective user and group ID to | |
58 | the owner of the executed file if the file has the `set-user-ID' | |
59 | or `set-group-ID' | |
60 | modes. | |
61 | The | |
62 | real | |
63 | user ID is not affected. | |
64 | .PP | |
65 | The | |
66 | .I name | |
67 | argument | |
68 | is a pointer to the name of the file | |
69 | to be executed. | |
70 | The pointers | |
71 | .IR arg [ 0 ], | |
72 | .IR arg [ 1 "] ..." | |
73 | address null-terminated strings. | |
74 | Conventionally | |
75 | .IR arg [ 0 ] | |
76 | is the name of the | |
77 | file. | |
78 | .PP | |
79 | From C, two interfaces are available. | |
80 | .I execl | |
81 | is useful when a known file with known arguments is | |
82 | being called; | |
83 | the arguments to | |
84 | .I execl | |
85 | are the character strings | |
86 | constituting the file and the arguments; | |
87 | the first argument is conventionally | |
88 | the same as the file name (or its last component). | |
89 | A 0 argument must end the argument list. | |
90 | .PP | |
91 | The | |
92 | .I execv | |
93 | version is useful when the number of arguments is unknown | |
94 | in advance; | |
95 | the arguments to | |
96 | .I execv | |
97 | are the name of the file to be | |
98 | executed and a vector of strings containing | |
99 | the arguments. | |
100 | The last argument string must be followed | |
101 | by a 0 pointer. | |
102 | .PP | |
103 | When a C program is executed, | |
104 | it is called as follows: | |
105 | .PP | |
106 | main(argc, argv, envp) | |
107 | .br | |
108 | int argc; | |
109 | .br | |
110 | char **argv, **envp; | |
111 | .PP | |
112 | where | |
113 | .IR argc "" | |
114 | is the argument count | |
115 | and | |
116 | .IR argv "" | |
117 | is an array of character pointers | |
118 | to the arguments themselves. | |
119 | As indicated, | |
120 | .IR argc "" | |
121 | is conventionally at least one | |
122 | and the first member of the array points to a | |
123 | string containing the name of the file. | |
124 | .PP | |
125 | .I Argv | |
126 | is directly usable in another | |
127 | .I execv | |
128 | because | |
129 | .IR argv [ argc ] | |
130 | is 0. | |
131 | .PP | |
132 | .I Envp | |
133 | is a pointer to an array of strings that constitute | |
134 | the | |
135 | .I environment | |
136 | of the process. | |
137 | Each string consists of a name, an ``='', and a null-terminated value. | |
138 | The array of pointers is terminated by a null pointer. | |
139 | The shell | |
140 | .IR sh (1) | |
141 | passes an environment entry for each global shell variable | |
142 | defined when the program is called. | |
143 | See | |
144 | .IR environ (5) | |
145 | for some conventionally | |
146 | used names. | |
147 | The C run-time start-off routine places a copy of | |
148 | .I envp | |
149 | in the global cell | |
150 | .I environ, | |
151 | which is used | |
152 | by | |
153 | .IR execv \ and \ execl | |
154 | to pass the environment to any subprograms executed by the | |
155 | current program. | |
156 | The | |
157 | .I exec | |
158 | routines use lower-level routines as follows | |
159 | to pass an environment explicitly: | |
160 | .RS | |
161 | .nf | |
162 | execve(file, argv, environ); | |
163 | execle(file, arg0, arg1, . . . , argn, 0, environ); | |
164 | .fi | |
165 | .RE | |
166 | .PP | |
167 | .I Execlp | |
168 | and | |
169 | .I execvp | |
170 | are called with the same arguments as | |
171 | .I execl | |
172 | and | |
173 | .I execv, | |
174 | but duplicate the shell's actions in searching for an executable | |
175 | file in a list of directories. | |
176 | The directory list is obtained from the environment. | |
177 | .SH FILES | |
178 | .ta \w'/bin/sh 'u | |
179 | /bin/sh shell, invoked if command file found | |
180 | by | |
181 | .I execlp | |
182 | or | |
183 | .I execvp | |
184 | .SH "SEE ALSO" | |
185 | fork(2), environ(5) | |
186 | .SH DIAGNOSTICS | |
187 | If the file cannot be found, | |
188 | if it is not executable, | |
189 | if it does not start with a valid magic number (see | |
190 | .IR a.out (5)), | |
191 | if maximum memory is exceeded, | |
192 | or if the arguments require too much space, | |
193 | a return | |
194 | constitutes the diagnostic; | |
195 | the return value is \-1. | |
196 | Even for the super-user, | |
197 | at least one of the execute-permission bits must be set for | |
198 | a file to be executed. | |
199 | .SH BUGS | |
200 | If | |
201 | .I execvp | |
202 | is called to execute a file that turns out to be a shell | |
203 | command file, | |
204 | and if it is impossible to execute the shell, | |
205 | the values of | |
206 | .I argv[0] | |
207 | and | |
208 | .I argv[\-1] | |
209 | will be modified before return. | |
210 | .SH "ASSEMBLER (PDP-11)" | |
211 | .DT | |
212 | (exec = 11.) | |
213 | .br | |
214 | .B sys exec; name; argv | |
215 | .PP | |
216 | (exece = 59.) | |
217 | .br | |
218 | .B sys exece; name; argv; envp | |
219 | .PP | |
220 | Plain | |
221 | .I exec | |
222 | is obsoleted by | |
223 | .I exece, | |
224 | but remains for historical reasons. | |
225 | .PP | |
226 | When the called file starts execution on the PDP11, | |
227 | the stack pointer points to a word containing the number of arguments. | |
228 | Just above | |
229 | this number is a list of pointers to the argument strings, | |
230 | followed by a null pointer, followed by the pointers to | |
231 | the environment strings and then another null pointer. | |
232 | The strings themselves follow; | |
233 | a 0 word is left at the very top of memory. | |
234 | .PP | |
235 | sp\(-> nargs | |
236 | .br | |
237 | arg0 | |
238 | .br | |
239 | ... | |
240 | .br | |
241 | argn | |
242 | .br | |
243 | 0 | |
244 | .br | |
245 | env0 | |
246 | .br | |
247 | ... | |
248 | .br | |
249 | envm | |
250 | .br | |
251 | 0 | |
252 | .PP | |
253 | arg0: <arg0\e0> | |
254 | .br | |
255 | ... | |
256 | .br | |
257 | env0: <env0\e0> | |
258 | .br | |
259 | 0 | |
260 | .PP | |
261 | On the Interdata 8/32, | |
262 | the stack begins at a conventional place | |
263 | (currently 0xD0000) | |
264 | and grows upwards. | |
265 | After | |
266 | .I exec, | |
267 | the layout of data on the stack is as follows. | |
268 | .PP | |
269 | .nf | |
270 | int 0 | |
271 | arg0: byte ... | |
272 | ... | |
273 | argp0: int arg0 | |
274 | ... | |
275 | int 0 | |
276 | envp0: int env0 | |
277 | ... | |
278 | int 0 | |
279 | %2\(-> space 40 | |
280 | int nargs | |
281 | int argp0 | |
282 | int envp0 | |
283 | %3\(-> | |
284 | .fi | |
285 | .PP | |
286 | This arrangement happens to conform well to C calling conventions. | |
287 | .PP | |
288 | On a VAX-11, the stack begins at 0x80000000 and grows towards lower- | |
289 | numbered addresses. After | |
290 | .IR exec , | |
291 | the layout of data on the stack is as follows. | |
292 | .PP | |
293 | .nf | |
294 | .ta \w' arg0: 'u | |
295 | ap \(-> | |
296 | fp \(-> | |
297 | sp \(-> .long nargs | |
298 | .long arg0 | |
299 | ... | |
300 | .long argn | |
301 | .long 0 | |
302 | .long env0 | |
303 | ... | |
304 | .long envn | |
305 | .long 0 | |
306 | arg0: .byte "arg0\e0" | |
307 | ... | |
308 | envn: .byte "envn\e0" | |
309 | .long 0 |