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