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