]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
c11b1abf | 2 | .\" and Copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified by Michael Haardt <michael@moria.de> | |
27 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com>: | |
29 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
30 | .\" Modified 1999-11-12 by Urs Thuermann <urs@isnogud.escape.de> | |
c11b1abf MK |
31 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
32 | .\" 2006-09-04 Michael Kerrisk <mtk.manpages@gmail.com> | |
e6b33ad7 | 33 | .\" Added list of process attributes that are not preserved on exec(). |
d739f5f8 MK |
34 | .\" 2007-09-14 Ollie Wild <aaw@google.com>, mtk |
35 | .\" Add text describing limits on command-line arguments + environment | |
fea681da | 36 | .\" |
09b8afdc | 37 | .TH EXECVE 2 2018-04-30 "Linux" "Linux Programmer's Manual" |
fea681da MK |
38 | .SH NAME |
39 | execve \- execute program | |
40 | .SH SYNOPSIS | |
41 | .B #include <unistd.h> | |
68e4db0a | 42 | .PP |
3f5755f6 | 43 | .BI "int execve(const char *" pathname ", char *const " argv "[], " |
7fdcdf23 MK |
44 | .br |
45 | .BI " char *const " envp []); | |
fea681da | 46 | .SH DESCRIPTION |
60a90ecd | 47 | .BR execve () |
3f5755f6 | 48 | executes the program referred to by \fIpathname\fP. |
b59de1c6 MK |
49 | This causes the program that is currently being run by the calling process |
50 | to be replaced with a new program, with newly initialized stack, heap, | |
51 | and (initialized and uninitialized) data segments. | |
52 | .PP | |
3f5755f6 | 53 | \fIpathname\fP must be either a binary executable, or a script |
cd24c687 | 54 | starting with a line of the form: |
efeece04 | 55 | .PP |
088a639b | 56 | .in +4n |
b76974c1 | 57 | .EX |
a8d55537 | 58 | \fB#!\fP \fIinterpreter \fP[optional-arg] |
b76974c1 | 59 | .EE |
cd24c687 | 60 | .in |
efeece04 | 61 | .PP |
e6b33ad7 | 62 | For details of the latter case, see "Interpreter scripts" below. |
efeece04 | 63 | .PP |
fea681da | 64 | \fIargv\fP is an array of argument strings passed to the new program. |
ce2ca8cc MK |
65 | By convention, the first of these strings (i.e., |
66 | .IR argv[0] ) | |
67 | should contain the filename associated with the file being executed. | |
fea681da | 68 | \fIenvp\fP is an array of strings, conventionally of the form |
a8d55537 | 69 | \fBkey=value\fP, which are passed as environment to the new program. |
f9429ced MK |
70 | The \fIargv\fP and \fIenvp\fP arrays must each include a null pointer |
71 | at the end of the array. | |
efeece04 | 72 | .PP |
c13182ef | 73 | The argument vector and environment can be accessed by the |
cd24c687 | 74 | called program's main function, when it is defined as: |
efeece04 | 75 | .PP |
088a639b | 76 | .in +4n |
b76974c1 | 77 | .EX |
a8d55537 | 78 | int main(int argc, char *argv[], char *envp[]) |
b76974c1 | 79 | .EE |
cd24c687 | 80 | .in |
efeece04 | 81 | .PP |
318519da MK |
82 | Note, however, that the use of a third argument to the main function |
83 | is not specified in POSIX.1; | |
84 | according to POSIX.1, | |
85 | the environment should be accessed via the external variable | |
86 | .BR environ (7). | |
efeece04 | 87 | .PP |
60a90ecd | 88 | .BR execve () |
7f02887d | 89 | does not return on success, and the text, initialized data, |
0f37a062 MK |
90 | uninitialized data (bss), and stack of the calling process are overwritten |
91 | according to the contents of the newly loaded program. | |
efeece04 | 92 | .PP |
af5b7450 | 93 | If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it |
60a90ecd MK |
94 | after a successful |
95 | .BR execve (). | |
efeece04 | 96 | .PP |
c49cdd1c | 97 | If the set-user-ID bit is set on the program file referred to by |
3f5755f6 | 98 | \fIpathname\fP, |
6aacaf94 | 99 | then the effective user ID of the calling process is changed |
ef0b8171 | 100 | to that of the owner of the program file. |
07b501d1 | 101 | Similarly, when the set-group-ID |
fea681da MK |
102 | bit of the program file is set the effective group ID of the calling |
103 | process is set to the group of the program file. | |
efeece04 | 104 | .PP |
29294c42 MK |
105 | The aforementioned transformations of the effective IDs are |
106 | .I not | |
9faff768 MK |
107 | performed (i.e., the set-user-ID and set-group-ID bits are ignored) |
108 | if any of the following is true: | |
29294c42 | 109 | .IP * 3 |
fca269a9 MK |
110 | the |
111 | .I no_new_privs | |
112 | attribute is set for the calling thread (see | |
113 | .BR prctl (2)); | |
114 | .IP * | |
29294c42 MK |
115 | the underlying filesystem is mounted |
116 | .I nosuid | |
117 | (the | |
118 | .B MS_NOSUID | |
119 | flag for | |
120 | .BR mount (2)); | |
121 | or | |
122 | .IP * | |
123 | the calling process is being ptraced. | |
124 | .PP | |
3b21b29e MK |
125 | The capabilities of the program file (see |
126 | .BR capabilities (7)) | |
661cfc7e | 127 | are also ignored if any of the above are true. |
3b21b29e | 128 | .PP |
07b501d1 MK |
129 | The effective user ID of the process is copied to the saved set-user-ID; |
130 | similarly, the effective group ID is copied to the saved set-group-ID. | |
c13182ef | 131 | This copying takes place after any effective ID changes that occur |
ed948c28 | 132 | because of the set-user-ID and set-group-ID mode bits. |
efeece04 | 133 | .PP |
b2210694 | 134 | The process's real UID and real GID, as well its supplementary group IDs, |
cf0588ad | 135 | are unchanged by a call to |
fc986cdd | 136 | .BR execve (). |
efeece04 | 137 | .PP |
3f624b93 | 138 | If the executable is an a.out dynamically linked |
07b501d1 | 139 | binary executable containing |
fea681da MK |
140 | shared-library stubs, the Linux dynamic linker |
141 | .BR ld.so (8) | |
c13182ef | 142 | is called at the start of execution to bring |
43151de3 | 143 | needed shared objects into memory |
fea681da | 144 | and link the executable with them. |
efeece04 | 145 | .PP |
3f624b93 | 146 | If the executable is a dynamically linked ELF executable, the |
fea681da | 147 | interpreter named in the PT_INTERP segment is used to load the needed |
43151de3 | 148 | shared objects. |
c13182ef | 149 | This interpreter is typically |
1941c8e7 | 150 | .I /lib/ld-linux.so.2 |
e6659f73 MK |
151 | for binaries linked with glibc (see |
152 | .BR ld-linux.so (8)). | |
efeece04 | 153 | .PP |
80a34ae3 MK |
154 | All process attributes are preserved during an |
155 | .BR execve (), | |
156 | except the following: | |
7bf5c019 | 157 | .IP * 3 |
c13182ef | 158 | The dispositions of any signals that are being caught are |
9ec8f860 CW |
159 | reset to the default |
160 | .RB ( signal (7)). | |
e4158924 | 161 | .IP * |
80a34ae3 MK |
162 | Any alternate signal stack is not preserved |
163 | .RB ( sigaltstack (2)). | |
e4158924 | 164 | .IP * |
80a34ae3 MK |
165 | Memory mappings are not preserved |
166 | .RB ( mmap (2)). | |
e4158924 | 167 | .IP * |
efbfd7ec | 168 | Attached System\ V shared memory segments are detached |
80a34ae3 | 169 | .RB ( shmat (2)). |
e4158924 | 170 | .IP * |
80a34ae3 MK |
171 | POSIX shared memory regions are unmapped |
172 | .RB ( shm_open (3)). | |
e4158924 | 173 | .IP * |
80a34ae3 MK |
174 | Open POSIX message queue descriptors are closed |
175 | .RB ( mq_overview (7)). | |
e4158924 | 176 | .IP * |
80a34ae3 MK |
177 | Any open POSIX named semaphores are closed |
178 | .RB ( sem_overview (7)). | |
e4158924 | 179 | .IP * |
80a34ae3 | 180 | POSIX timers are not preserved |
804f03e6 | 181 | .RB ( timer_create (2)). |
e4158924 | 182 | .IP * |
80a34ae3 MK |
183 | Any open directory streams are closed |
184 | .RB ( opendir (3)). | |
e4158924 | 185 | .IP * |
80a34ae3 MK |
186 | Memory locks are not preserved |
187 | .RB ( mlock (2), | |
188 | .BR mlockall (2)). | |
e4158924 | 189 | .IP * |
80a34ae3 MK |
190 | Exit handlers are not preserved |
191 | .RB ( atexit (3), | |
192 | .BR on_exit (3)). | |
2fb19a16 MK |
193 | .IP * |
194 | The floating-point environment is reset to the default (see | |
195 | .BR fenv (3)). | |
80a34ae3 | 196 | .PP |
c13182ef | 197 | The process attributes in the preceding list are all specified |
ce1ff0f6 | 198 | in POSIX.1. |
c13182ef | 199 | The following Linux-specific process attributes are also |
80a34ae3 MK |
200 | not preserved during an |
201 | .BR execve (): | |
e4158924 | 202 | .IP * 3 |
c13182ef | 203 | The |
80a34ae3 | 204 | .BR prctl (2) |
c13182ef | 205 | .B PR_SET_DUMPABLE |
80a34ae3 MK |
206 | flag is set, |
207 | unless a set-user-ID or set-group ID program is being executed, | |
208 | in which case it is cleared. | |
e4158924 | 209 | .IP * |
c13182ef | 210 | The |
80a34ae3 MK |
211 | .BR prctl (2) |
212 | .B PR_SET_KEEPCAPS | |
213 | flag is cleared. | |
e4158924 | 214 | .IP * |
30cc7676 MK |
215 | (Since Linux 2.4.36 / 2.6.23) |
216 | If a set-user-ID or set-group-ID program is being executed, | |
217 | then the parent death signal set by | |
218 | .BR prctl (2) | |
219 | .B PR_SET_PDEATHSIG | |
220 | flag is cleared. | |
221 | .IP * | |
fe247268 MK |
222 | The process name, as set by |
223 | .BR prctl (2) | |
0daa9e92 | 224 | .B PR_SET_NAME |
fe247268 | 225 | (and displayed by |
80d26cef | 226 | .IR "ps\ \-o comm" ), |
fe247268 | 227 | is reset to the name of the new executable file. |
e4158924 | 228 | .IP * |
8e9412e7 MK |
229 | The |
230 | .B SECBIT_KEEP_CAPS | |
231 | .I securebits | |
232 | flag is cleared. | |
233 | See | |
234 | .BR capabilities (7). | |
235 | .IP * | |
8bd58774 MK |
236 | The termination signal is reset to |
237 | .B SIGCHLD | |
80a34ae3 MK |
238 | (see |
239 | .BR clone (2)). | |
8a76b19e KE |
240 | .IP * |
241 | The file descriptor table is unshared, undoing the effect of the | |
242 | .B CLONE_FILES | |
243 | flag of | |
244 | .BR clone (2). | |
80a34ae3 MK |
245 | .PP |
246 | Note the following further points: | |
e4158924 | 247 | .IP * 3 |
7fd8a3c9 | 248 | All threads other than the calling thread are destroyed during an |
80a34ae3 MK |
249 | .BR execve (). |
250 | Mutexes, condition variables, and other pthreads objects are not preserved. | |
e4158924 | 251 | .IP * |
80a34ae3 MK |
252 | The equivalent of \fIsetlocale(LC_ALL, "C")\fP |
253 | is executed at program start-up. | |
e4158924 | 254 | .IP * |
ce1ff0f6 | 255 | POSIX.1 specifies that the dispositions of any signals that |
80a34ae3 | 256 | are ignored or set to the default are left unchanged. |
ce1ff0f6 | 257 | POSIX.1 specifies one exception: if |
8bd58774 MK |
258 | .B SIGCHLD |
259 | is being ignored, | |
c13182ef | 260 | then an implementation may leave the disposition unchanged or |
80a34ae3 | 261 | reset it to the default; Linux does the former. |
e4158924 | 262 | .IP * |
d9bfdb9c | 263 | Any outstanding asynchronous I/O operations are canceled |
80a34ae3 MK |
264 | .RB ( aio_read (3), |
265 | .BR aio_write (3)). | |
e4158924 | 266 | .IP * |
c13182ef | 267 | For the handling of capabilities during |
2777b1ca | 268 | .BR execve (), |
80a34ae3 MK |
269 | see |
270 | .BR capabilities (7). | |
e4158924 | 271 | .IP * |
988db661 | 272 | By default, file descriptors remain open across an |
d6f223a7 | 273 | .BR execve (). |
3a16ac7a MK |
274 | File descriptors that are marked close-on-exec are closed; |
275 | see the description of | |
0daa9e92 | 276 | .B FD_CLOEXEC |
d6f223a7 MK |
277 | in |
278 | .BR fcntl (2). | |
279 | (If a file descriptor is closed, this will cause the release | |
280 | of all record locks obtained on the underlying file by this process. | |
281 | See | |
282 | .BR fcntl (2) | |
283 | for details.) | |
ce1ff0f6 | 284 | POSIX.1 says that if file descriptors 0, 1, and 2 would |
d6f223a7 MK |
285 | otherwise be closed after a successful |
286 | .BR execve (), | |
86c91a79 | 287 | and the process would gain privilege because the set-user-ID or |
ed948c28 | 288 | set-group_ID mode bit was set on the executed file, |
d6f223a7 MK |
289 | then the system may open an unspecified file for each of these |
290 | file descriptors. | |
291 | As a general principle, no portable program, whether privileged or not, | |
988db661 | 292 | can assume that these three file descriptors will remain |
d6f223a7 MK |
293 | closed across an |
294 | .BR execve (). | |
295 | .\" On Linux it appears that these file descriptors are | |
296 | .\" always open after an execve(), and it looks like | |
297 | .\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007 | |
e6b33ad7 | 298 | .SS Interpreter scripts |
988db661 | 299 | An interpreter script is a text file that has execute |
e6b33ad7 | 300 | permission enabled and whose first line is of the form: |
efeece04 | 301 | .PP |
088a639b | 302 | .in +4n |
b8302363 | 303 | .EX |
a8d55537 | 304 | \fB#!\fP \fIinterpreter \fP[optional-arg] |
b8302363 | 305 | .EE |
e6b33ad7 | 306 | .in |
efeece04 | 307 | .PP |
988db661 MK |
308 | The |
309 | .I interpreter | |
246104f0 | 310 | must be a valid pathname for an executable file. |
988db661 | 311 | If the |
3f5755f6 | 312 | .I pathname |
e6b33ad7 MK |
313 | argument of |
314 | .BR execve () | |
988db661 | 315 | specifies an interpreter script, then |
e6b33ad7 MK |
316 | .I interpreter |
317 | will be invoked with the following arguments: | |
efeece04 | 318 | .PP |
088a639b | 319 | .in +4n |
b8302363 | 320 | .EX |
3f5755f6 | 321 | \fIinterpreter\fP [optional-arg] \fIpathname\fP arg... |
b8302363 | 322 | .EE |
e6b33ad7 | 323 | .in |
efeece04 | 324 | .PP |
e6b33ad7 MK |
325 | where |
326 | .I arg... | |
988db661 | 327 | is the series of words pointed to by the |
e6b33ad7 | 328 | .I argv |
988db661 | 329 | argument of |
a2954fe6 MK |
330 | .BR execve (), |
331 | starting at | |
332 | .IR argv [1]. | |
efeece04 | 333 | .PP |
e6b33ad7 MK |
334 | For portable use, |
335 | .I optional-arg | |
336 | should either be absent, or be specified as a single word (i.e., it | |
337 | should not contain white space); see NOTES below. | |
efeece04 | 338 | .PP |
246104f0 MK |
339 | Since Linux 2.6.28, |
340 | .\" commit bf2a9a39639b8b51377905397a5005f444e9a892 | |
341 | the kernel permits the interpreter of a script to itself be a script. | |
342 | This permission is recursive, up to a limit of four recursions, | |
d673870e | 343 | so that the interpreter may be a script which is interpreted by a script, |
246104f0 | 344 | and so on. |
73d8cece | 345 | .SS Limits on size of arguments and environment |
008f1ecc | 346 | Most UNIX implementations impose some limit on the total size |
d739f5f8 MK |
347 | of the command-line argument |
348 | .RI ( argv ) | |
349 | and environment | |
350 | .RI ( envp ) | |
351 | strings that may be passed to a new program. | |
352 | POSIX.1 allows an implementation to advertise this limit using the | |
0daa9e92 | 353 | .B ARG_MAX |
d739f5f8 MK |
354 | constant (either defined in |
355 | .I <limits.h> | |
356 | or available at run time using the call | |
357 | .IR "sysconf(_SC_ARG_MAX)" ). | |
efeece04 | 358 | .PP |
d739f5f8 MK |
359 | On Linux prior to kernel 2.6.23, the memory used to store the |
360 | environment and argument strings was limited to 32 pages | |
361 | (defined by the kernel constant | |
362 | .BR MAX_ARG_PAGES ). | |
363 | On architectures with a 4-kB page size, | |
c4b7e5ac | 364 | this yields a maximum size of 128\ kB. |
efeece04 | 365 | .PP |
d739f5f8 MK |
366 | On kernel 2.6.23 and later, most architectures support a size limit |
367 | derived from the soft | |
368 | .B RLIMIT_STACK | |
369 | resource limit (see | |
e5a7fca5 MK |
370 | .BR getrlimit (2)) |
371 | that is in force at the time of the | |
372 | .BR execve () | |
373 | call. | |
f202015b MK |
374 | (Architectures with no memory management unit are excepted: |
375 | they maintain the limit that was in effect before kernel 2.6.23.) | |
376 | This change allows programs to have a much larger | |
d739f5f8 | 377 | argument and/or environment list. |
f202015b MK |
378 | .\" For some background on the changes to ARG_MAX in kernels 2.6.23 and |
379 | .\" 2.6.25, see: | |
380 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786 | |
381 | .\" http://bugzilla.kernel.org/show_bug.cgi?id=10095 | |
382 | .\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, | |
383 | .\" checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. | |
384 | For these architectures, the total size is limited to 1/4 of the allowed | |
385 | stack size. | |
386 | (Imposing the 1/4-limit | |
d739f5f8 | 387 | ensures that the new program always has some stack space.) |
d739f5f8 MK |
388 | .\" Ollie: That doesn't include the lists of pointers, though, |
389 | .\" so the actual usage is a bit higher (1 pointer per argument). | |
4a696f5e MK |
390 | Additionally, the total size is limited to 3/4 of the value |
391 | of the kernel constant | |
392 | .B _STK_LIM | |
393 | (8 Mibibytes). | |
f202015b | 394 | Since Linux 2.6.25, |
3a66e329 | 395 | the kernel also places a floor of 32 pages on this size limit, |
f202015b MK |
396 | so that, even when |
397 | .BR RLIMIT_STACK | |
398 | is set very low, | |
399 | applications are guaranteed to have at least as much argument and | |
400 | environment space as was provided by Linux 2.6.23 and earlier. | |
401 | (This guarantee was not provided in Linux 2.6.23 and 2.6.24.) | |
402 | Additionally, the limit per string is 32 pages (the kernel constant | |
403 | .BR MAX_ARG_STRLEN ), | |
404 | and the maximum number of strings is 0x7FFFFFFF. | |
47297adb | 405 | .SH RETURN VALUE |
60a90ecd MK |
406 | On success, |
407 | .BR execve () | |
408 | does not return, on error \-1 is returned, and | |
fea681da MK |
409 | .I errno |
410 | is set appropriately. | |
411 | .SH ERRORS | |
412 | .TP | |
413 | .B E2BIG | |
c13182ef | 414 | The total number of bytes in the environment |
4989c2f3 | 415 | .RI ( envp ) |
c13182ef | 416 | and argument list |
4989c2f3 MK |
417 | .RI ( argv ) |
418 | is too large. | |
fea681da MK |
419 | .TP |
420 | .B EACCES | |
421 | Search permission is denied on a component of the path prefix of | |
3f5755f6 | 422 | .I pathname |
fea681da MK |
423 | or the name of a script interpreter. |
424 | (See also | |
ad7cc990 | 425 | .BR path_resolution (7).) |
fea681da MK |
426 | .TP |
427 | .B EACCES | |
428 | The file or a script interpreter is not a regular file. | |
429 | .TP | |
430 | .B EACCES | |
431 | Execute permission is denied for the file or a script or ELF interpreter. | |
432 | .TP | |
433 | .B EACCES | |
9ee4a2b6 | 434 | The filesystem is mounted |
fea681da MK |
435 | .IR noexec . |
436 | .TP | |
ebd381ba MK |
437 | .BR EAGAIN " (since Linux 3.1)" |
438 | .\" commit 72fa59970f8698023045ab0713d66f3f4f96945c | |
439 | Having changed its real UID using one of the | |
440 | .BR set*uid () | |
441 | calls, the caller was\(emand is now still\(emabove its | |
442 | .BR RLIMIT_NPROC | |
443 | resource limit (see | |
444 | .BR setrlimit (2)). | |
445 | For a more detailed explanation of this error, see NOTES. | |
446 | .TP | |
fea681da | 447 | .B EFAULT |
3f5755f6 | 448 | .I pathname |
30410190 MK |
449 | or one of the pointers in the vectors |
450 | .I argv | |
451 | or | |
452 | .I envp | |
fea681da MK |
453 | points outside your accessible address space. |
454 | .TP | |
455 | .B EINVAL | |
456 | An ELF executable had more than one PT_INTERP segment (i.e., tried to | |
457 | name more than one interpreter). | |
458 | .TP | |
459 | .B EIO | |
460 | An I/O error occurred. | |
461 | .TP | |
462 | .B EISDIR | |
463 | An ELF interpreter was a directory. | |
464 | .TP | |
465 | .B ELIBBAD | |
d9bfdb9c | 466 | An ELF interpreter was not in a recognized format. |
fea681da MK |
467 | .TP |
468 | .B ELOOP | |
469 | Too many symbolic links were encountered in resolving | |
3f5755f6 | 470 | .I pathname |
fea681da MK |
471 | or the name of a script or ELF interpreter. |
472 | .TP | |
246104f0 MK |
473 | .B ELOOP |
474 | The maximum recursion limit was reached during recursive script | |
475 | interpretation (see "Interpreter scripts", above). | |
476 | Before Linux 3.8, | |
477 | .\" commit d740269867021faf4ce38a449353d2b986c34a67 | |
478 | the error produced for this case was | |
479 | .BR ENOEXEC . | |
480 | .TP | |
fea681da | 481 | .B EMFILE |
26c32fab | 482 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
483 | .TP |
484 | .B ENAMETOOLONG | |
3f5755f6 | 485 | .I pathname |
fea681da MK |
486 | is too long. |
487 | .TP | |
488 | .B ENFILE | |
e258766b | 489 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
490 | .TP |
491 | .B ENOENT | |
c13182ef | 492 | The file |
3f5755f6 | 493 | .I pathname |
fea681da | 494 | or a script or ELF interpreter does not exist, or a shared library |
0b4ac988 | 495 | .\" FIXME but see http://sourceware.org/bugzilla/show_bug.cgi?id=12241 |
2a79c2ac | 496 | needed for the file or interpreter cannot be found. |
fea681da MK |
497 | .TP |
498 | .B ENOEXEC | |
d9bfdb9c | 499 | An executable is not in a recognized format, is for the wrong |
fea681da MK |
500 | architecture, or has some other format error that means it cannot be |
501 | executed. | |
502 | .TP | |
503 | .B ENOMEM | |
504 | Insufficient kernel memory was available. | |
505 | .TP | |
506 | .B ENOTDIR | |
507 | A component of the path prefix of | |
3f5755f6 | 508 | .I pathname |
fea681da MK |
509 | or a script or ELF interpreter is not a directory. |
510 | .TP | |
511 | .B EPERM | |
9ee4a2b6 | 512 | The filesystem is mounted |
fea681da | 513 | .IR nosuid , |
c13182ef | 514 | the user is not the superuser, |
81069819 | 515 | and the file has the set-user-ID or set-group-ID bit set. |
fea681da MK |
516 | .TP |
517 | .B EPERM | |
518 | The process is being traced, the user is not the superuser and the | |
81069819 | 519 | file has the set-user-ID or set-group-ID bit set. |
fea681da | 520 | .TP |
8cd11c42 MK |
521 | .B EPERM |
522 | A "capability-dumb" applications would not obtain the full set of | |
523 | permitted capabilities granted by the executable file. | |
524 | See | |
525 | .BR capabilities (7). | |
526 | .TP | |
fea681da | 527 | .B ETXTBSY |
a72a6174 | 528 | The specified executable was open for writing by one or more processes. |
47297adb | 529 | .SH CONFORMING TO |
ce1ff0f6 | 530 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
c95f9f2c MK |
531 | POSIX does not document the #! behavior, but it exists |
532 | (with some variations) on other UNIX systems. | |
97c1eac8 MK |
533 | .\" SVr4 documents additional error |
534 | .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not | |
535 | .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, | |
536 | .\" EISDIR or ELIBBAD error conditions. | |
fea681da | 537 | .SH NOTES |
aba7005c MK |
538 | One sometimes sees |
539 | .BR execve () | |
540 | (and the related functions described in | |
541 | .BR exec (3)) | |
542 | described as "executing a | |
543 | .I new | |
544 | process" (or similar). | |
545 | This is a highly misleading description: | |
546 | there is no new process; | |
547 | many attributes of the calling process remain unchanged | |
548 | (in particular, its PID). | |
549 | All that | |
550 | .BR execve (2) | |
551 | does is arrange for an existing process (the calling process) | |
552 | to execute a new program. | |
553 | .PP | |
0bfa087b MK |
554 | Set-user-ID and set-group-ID processes can not be |
555 | .BR ptrace (2)d. | |
efeece04 | 556 | .PP |
9ee4a2b6 | 557 | The result of mounting a filesystem |
fea681da | 558 | .I nosuid |
d6f223a7 | 559 | varies across Linux kernel versions: |
c13182ef | 560 | some will refuse execution of set-user-ID and set-group-ID |
81069819 | 561 | executables when this would |
60ae21db | 562 | give the user powers they did not have already (and return |
682edefb | 563 | .BR EPERM ), |
c13182ef | 564 | some will just ignore the set-user-ID and set-group-ID bits and |
1e321034 MK |
565 | .BR exec () |
566 | successfully. | |
efeece04 | 567 | .PP |
e6bec78c | 568 | On Linux, |
45696074 | 569 | .I argv |
e6bec78c | 570 | and |
0c42642f | 571 | .I envp |
e6bec78c MK |
572 | can be specified as NULL. |
573 | In both cases, this has the same effect as specifying the argument | |
b437fdd9 | 574 | as a pointer to a list containing a single null pointer. |
eb24aedc MK |
575 | .B "Do not take advantage of this nonstandard and nonportable misfeature!" |
576 | On many other UNIX systems, specifying | |
577 | .I argv | |
578 | as NULL will result in an error | |
34dcae54 | 579 | .RB ( EFAULT ). |
eb24aedc MK |
580 | .I Some |
581 | other UNIX systems treat the | |
582 | .I envp==NULL | |
583 | case the same as Linux. | |
75b94dc3 | 584 | .\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but |
45696074 | 585 | .\" HP-UX 11 is like Linux -- mtk, Apr 2007 |
45696074 | 586 | .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 |
bf501102 | 587 | .\" Bug rejected (because fix would constitute an ABI change). |
45696074 | 588 | .\" |
efeece04 | 589 | .PP |
ce1ff0f6 | 590 | POSIX.1 says that values returned by |
3a9dc9ff MK |
591 | .BR sysconf (3) |
592 | should be invariant over the lifetime of a process. | |
593 | However, since Linux 2.6.23, if the | |
594 | .BR RLIMIT_STACK | |
595 | resource limit changes, then the value reported by | |
596 | .B _SC_ARG_MAX | |
597 | will also change, | |
598 | to reflect the fact that the limit on space for holding | |
599 | command-line arguments and environment variables has changed. | |
efeece04 | 600 | .PP |
3a4b02b2 MK |
601 | In most cases where |
602 | .BR execve () | |
603 | fails, control returns to the original executable image, | |
604 | and the caller of | |
605 | .BR execve () | |
606 | can then handle the error. | |
607 | However, in (rare) cases (typically caused by resource exhaustion), | |
608 | failure may occur past the point of no return: | |
609 | the original executable image has been torn down, | |
610 | but the new image could not be completely built. | |
611 | In such cases, the kernel kills the process with a | |
612 | .BR SIGKILL | |
613 | signal. | |
4c4d30d8 MK |
614 | .\" |
615 | .SS Interpreter scripts | |
616 | A maximum line length of 127 characters is allowed for the first line in | |
b2210694 | 617 | an interpreter script. |
efeece04 | 618 | .PP |
4c4d30d8 MK |
619 | The semantics of the |
620 | .I optional-arg | |
621 | argument of an interpreter script vary across implementations. | |
622 | On Linux, the entire string following the | |
623 | .I interpreter | |
624 | name is passed as a single argument to the interpreter, | |
625 | and this string can include white space. | |
626 | However, behavior differs on some other systems. | |
627 | Some systems | |
628 | .\" e.g., Solaris 8 | |
629 | use the first white space to terminate | |
630 | .IR optional-arg . | |
631 | On some systems, | |
632 | .\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onward | |
633 | an interpreter script can have multiple arguments, | |
634 | and white spaces in | |
635 | .I optional-arg | |
636 | are used to delimit the arguments. | |
efeece04 | 637 | .PP |
4c4d30d8 MK |
638 | Linux ignores the set-user-ID and set-group-ID bits on scripts. |
639 | .\" | |
ebd381ba MK |
640 | .\" .SH BUGS |
641 | .\" Some Linux versions have failed to check permissions on ELF | |
642 | .\" interpreters. This is a security hole, because it allows users to | |
643 | .\" open any file, such as a rewinding tape device, for reading. Some | |
644 | .\" Linux versions have also had other security holes in | |
645 | .\" .BR execve () | |
646 | .\" that could be exploited for denial of service by a suitably crafted | |
647 | .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. | |
648 | .SS execve() and EAGAIN | |
649 | A more detailed explanation of the | |
650 | .BR EAGAIN | |
651 | error that can occur (since Linux 3.1) when calling | |
652 | .BR execve () | |
653 | is as follows. | |
efeece04 | 654 | .PP |
ebd381ba MK |
655 | The |
656 | .BR EAGAIN | |
657 | error can occur when a | |
658 | .I preceding | |
659 | call to | |
660 | .BR setuid (2), | |
661 | .BR setreuid (2), | |
662 | or | |
663 | .BR setresuid (2) | |
664 | caused the real user ID of the process to change, | |
665 | and that change caused the process to exceed its | |
666 | .BR RLIMIT_NPROC | |
667 | resource limit (i.e., the number of processes belonging | |
668 | to the new real UID exceeds the resource limit). | |
83490231 | 669 | From Linux 2.6.0 to 3.0, this caused the |
ebd381ba MK |
670 | .BR set*uid () |
671 | call to fail. | |
83490231 MK |
672 | (Prior to 2.6, |
673 | .\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 | |
674 | the resource limit was not imposed on processes that | |
675 | changed their user IDs.) | |
efeece04 | 676 | .PP |
ebd381ba MK |
677 | Since Linux 3.1, the scenario just described no longer causes the |
678 | .BR set*uid () | |
679 | call to fail, | |
680 | because it too often led to security holes where buggy applications | |
681 | didn't check the return status and assumed | |
682 | that\(emif the caller had root privileges\(emthe call would always succeed. | |
683 | Instead, the | |
684 | .BR set*uid () | |
685 | calls now successfully change the real UID, | |
686 | but the kernel sets an internal flag, named | |
687 | .BR PF_NPROC_EXCEEDED , | |
688 | to note that the | |
689 | .BR RLIMIT_NPROC | |
690 | resource limit has been exceeded. | |
adab861a MK |
691 | If the |
692 | .BR PF_NPROC_EXCEEDED | |
693 | flag is set and the resource limit is still | |
694 | exceeded at the time of a subsequent | |
ebd381ba MK |
695 | .BR execve () |
696 | call, that call fails with the error | |
697 | .BR EAGAIN . | |
698 | This kernel logic ensures that the | |
699 | .BR RLIMIT_NPROC | |
700 | resource limit is still enforced for the | |
701 | common privileged daemon workflow\(emnamely, | |
702 | .BR fork (2) | |
703 | + | |
704 | .BR set*uid () | |
705 | + | |
706 | .BR execve (). | |
efeece04 | 707 | .PP |
ebd381ba MK |
708 | If the resource limit was not still exceeded at the time of the |
709 | .BR execve () | |
710 | call | |
711 | (because other processes belonging to this real UID terminated between the | |
84ca1d33 | 712 | .BR set*uid () |
ebd381ba MK |
713 | call and the |
714 | .BR execve () | |
715 | call), then the | |
716 | .BR execve () | |
717 | call succeeds and the kernel clears the | |
718 | .BR PF_NPROC_EXCEEDED | |
719 | process flag. | |
720 | The flag is also cleared if a subsequent call to | |
721 | .BR fork (2) | |
722 | by this process succeeds. | |
8c87824d | 723 | .SS Historical |
b4112efb | 724 | With UNIX\ V6, the argument list of an |
1e321034 MK |
725 | .BR exec () |
726 | call was ended by 0, | |
fea681da MK |
727 | while the argument list of |
728 | .I main | |
677f4766 MK |
729 | was ended by \-1. |
730 | Thus, this argument list was not directly usable in a further | |
c13182ef | 731 | .BR exec () |
1e321034 | 732 | call. |
b4112efb | 733 | Since UNIX\ V7, both are NULL. |
800a8a42 MK |
734 | .\" |
735 | .\" .SH BUGS | |
736 | .\" Some Linux versions have failed to check permissions on ELF | |
737 | .\" interpreters. This is a security hole, because it allows users to | |
738 | .\" open any file, such as a rewinding tape device, for reading. Some | |
739 | .\" Linux versions have also had other security holes in | |
740 | .\" .BR execve () | |
741 | .\" that could be exploited for denial of service by a suitably crafted | |
742 | .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. | |
e6b33ad7 | 743 | .SH EXAMPLE |
6c48afff | 744 | The following program is designed to be execed by the second program below. |
5f8ddde3 | 745 | It just echoes its command-line arguments, one per line. |
efeece04 | 746 | .PP |
088a639b | 747 | .in +4n |
47f743f1 | 748 | .EX |
e6b33ad7 MK |
749 | /* myecho.c */ |
750 | ||
751 | #include <stdio.h> | |
752 | #include <stdlib.h> | |
753 | ||
754 | int | |
755 | main(int argc, char *argv[]) | |
756 | { | |
757 | int j; | |
758 | ||
759 | for (j = 0; j < argc; j++) | |
d1a71985 | 760 | printf("argv[%d]: %s\en", j, argv[j]); |
e6b33ad7 MK |
761 | |
762 | exit(EXIT_SUCCESS); | |
763 | } | |
47f743f1 | 764 | .EE |
e6b33ad7 | 765 | .in |
efeece04 | 766 | .PP |
e6b33ad7 MK |
767 | This program can be used to exec the program named in its command-line |
768 | argument: | |
47f743f1 | 769 | .PP |
088a639b | 770 | .in +4n |
47f743f1 | 771 | .EX |
e6b33ad7 MK |
772 | /* execve.c */ |
773 | ||
774 | #include <stdio.h> | |
775 | #include <stdlib.h> | |
776 | #include <unistd.h> | |
e6b33ad7 MK |
777 | |
778 | int | |
779 | main(int argc, char *argv[]) | |
780 | { | |
781 | char *newargv[] = { NULL, "hello", "world", NULL }; | |
782 | char *newenviron[] = { NULL }; | |
783 | ||
6b34fb3f | 784 | if (argc != 2) { |
d1a71985 | 785 | fprintf(stderr, "Usage: %s <file\-to\-exec>\en", argv[0]); |
5a6194a4 | 786 | exit(EXIT_FAILURE); |
6b34fb3f MK |
787 | } |
788 | ||
e6b33ad7 MK |
789 | newargv[0] = argv[1]; |
790 | ||
791 | execve(argv[1], newargv, newenviron); | |
312d8fde | 792 | perror("execve"); /* execve() returns only on error */ |
e6b33ad7 MK |
793 | exit(EXIT_FAILURE); |
794 | } | |
47f743f1 | 795 | .EE |
e6b33ad7 | 796 | .in |
efeece04 | 797 | .PP |
e6b33ad7 | 798 | We can use the second program to exec the first as follows: |
efeece04 | 799 | .PP |
088a639b | 800 | .in +4n |
47f743f1 | 801 | .EX |
b43a3b30 MK |
802 | .RB "$" " cc myecho.c \-o myecho" |
803 | .RB "$" " cc execve.c \-o execve" | |
804 | .RB "$" " ./execve ./myecho" | |
e6b33ad7 MK |
805 | argv[0]: ./myecho |
806 | argv[1]: hello | |
807 | argv[2]: world | |
47f743f1 | 808 | .EE |
e6b33ad7 | 809 | .in |
efeece04 | 810 | .PP |
e6b33ad7 MK |
811 | We can also use these programs to demonstrate the use of a script |
812 | interpreter. | |
813 | To do this we create a script whose "interpreter" is our | |
814 | .I myecho | |
815 | program: | |
efeece04 | 816 | .PP |
088a639b | 817 | .in +4n |
47f743f1 | 818 | .EX |
1a212a01 MK |
819 | .RB "$" " cat > script" |
820 | .B #!./myecho script-arg | |
b43a3b30 | 821 | .B ^D |
1a212a01 | 822 | .RB "$" " chmod +x script" |
47f743f1 | 823 | .EE |
e6b33ad7 | 824 | .in |
efeece04 | 825 | .PP |
e6b33ad7 | 826 | We can then use our program to exec the script: |
efeece04 | 827 | .PP |
088a639b | 828 | .in +4n |
47f743f1 | 829 | .EX |
1a212a01 | 830 | .RB "$" " ./execve ./script" |
e6b33ad7 MK |
831 | argv[0]: ./myecho |
832 | argv[1]: script-arg | |
1a212a01 | 833 | argv[2]: ./script |
e6b33ad7 MK |
834 | argv[3]: hello |
835 | argv[4]: world | |
47f743f1 | 836 | .EE |
e6b33ad7 | 837 | .in |
47297adb | 838 | .SH SEE ALSO |
fea681da | 839 | .BR chmod (2), |
a940759f | 840 | .BR execveat (2), |
fea681da | 841 | .BR fork (2), |
2cf607f1 | 842 | .BR get_robust_list (2), |
6aacaf94 | 843 | .BR ptrace (2), |
f77c624f | 844 | .BR exec (3), |
9d7f3355 | 845 | .BR fexecve (3), |
d739f5f8 | 846 | .BR getopt (3), |
e6aa1ec8 | 847 | .BR system (3), |
53a1443c | 848 | .BR credentials (7), |
f0c34053 | 849 | .BR environ (7), |
ad7cc990 | 850 | .BR path_resolution (7), |
fea681da | 851 | .BR ld.so (8) |