1EXECVE(2) Linux Programmer's Manual EXECVE(2)
2
6 execve - execute program
7
9 #include <unistd.h>
10 int execve(const char *filename, char *const argv[],
12 char *const envp[]);
13
15 execve() executes the program pointed to by filename. filename must be
16 either a binary executable, or a script starting with a line of the
17 form:
18 #! interpreter [optional-arg]
20 For details of the latter case, see "Interpreter scripts" below.
22 argv is an array of argument strings passed to the new program. By
24 convention, the first of these strings (i.e., argv[0]) should contain
25 the filename associated with the file being executed. envp is an array
26 of strings, conventionally of the form key=value, which are passed as
27 environment to the new program. The argv and envp arrays must each
28 include a null pointer at the end of the array.
29 The argument vector and environment can be accessed by the called pro‐
31 gram's main function, when it is defined as:
32 int main(int argc, char *argv[], char *envp[])
34 Note, however, that the use of a third argument to the main function is
36 not specified in POSIX.1; according to POSIX.1, the environment should
37 be accessed via the external variable environ(7).
38 execve() does not return on success, and the text, initialized data,
40 uninitialized data (bss), and stack of the calling process are over‐
41 written according to the contents of the newly loaded program.
42 If the current program is being ptraced, a SIGTRAP signal is sent to it
44 after a successful execve().
45 If the set-user-ID bit is set on the program file pointed to by file‐
47 name, then the effective user ID of the calling process is changed to
48 that of the owner of the program file. Similarly, when the set-group-
49 ID bit of the program file is set the effective group ID of the calling
50 process is set to the group of the program file.
51 The aforementioned transformations of the effective IDs are not per‐
53 formed (i.e., the set-user-ID and set-group-ID bits are ignored) if any
54 of the following is true:
55 * the no_new_privs attribute is set for the calling thread (see
57 prctl(2));
58 * the underlying filesystem is mounted nosuid (the MS_NOSUID flag for
60 mount(2)); or
61 * the calling process is being ptraced.
63 The capabilities of the program file (see capabilities(7)) are also
65 ignored if any of the above are true.
66 The effective user ID of the process is copied to the saved set-user-
68 ID; similarly, the effective group ID is copied to the saved set-group-
69 ID. This copying takes place after any effective ID changes that occur
70 because of the set-user-ID and set-group-ID mode bits.
71 The process's real UID and real GID, as well its supplementary group
73 IDs, are unchanged by a call to execve().
74 If the executable is an a.out dynamically linked binary executable con‐
76 taining shared-library stubs, the Linux dynamic linker ld.so(8) is
77 called at the start of execution to bring needed shared objects into
78 memory and link the executable with them.
79 If the executable is a dynamically linked ELF executable, the inter‐
81 preter named in the PT_INTERP segment is used to load the needed shared
82 objects. This interpreter is typically /lib/ld-linux.so.2 for binaries
83 linked with glibc (see ld-linux.so(8)).
84 All process attributes are preserved during an execve(), except the
86 following:
87 * The dispositions of any signals that are being caught are reset to
89 the default (signal(7)).
90 * Any alternate signal stack is not preserved (sigaltstack(2)).
92 * Memory mappings are not preserved (mmap(2)).
94 * Attached System V shared memory segments are detached (shmat(2)).
96 * POSIX shared memory regions are unmapped (shm_open(3)).
98 * Open POSIX message queue descriptors are closed (mq_overview(7)).
100 * Any open POSIX named semaphores are closed (sem_overview(7)).
102 * POSIX timers are not preserved (timer_create(2)).
104 * Any open directory streams are closed (opendir(3)).
106 * Memory locks are not preserved (mlock(2), mlockall(2)).
108 * Exit handlers are not preserved (atexit(3), on_exit(3)).
110 * The floating-point environment is reset to the default (see
112 fenv(3)).
113 The process attributes in the preceding list are all specified in
115 POSIX.1. The following Linux-specific process attributes are also not
116 preserved during an execve():
117 * The prctl(2) PR_SET_DUMPABLE flag is set, unless a set-user-ID or
119 set-group ID program is being executed, in which case it is cleared.
120 * The prctl(2) PR_SET_KEEPCAPS flag is cleared.
122 * (Since Linux 2.4.36 / 2.6.23) If a set-user-ID or set-group-ID pro‐
124 gram is being executed, then the parent death signal set by prctl(2)
125 PR_SET_PDEATHSIG flag is cleared.
126 * The process name, as set by prctl(2) PR_SET_NAME (and displayed by
128 ps -o comm), is reset to the name of the new executable file.
129 * The SECBIT_KEEP_CAPS securebits flag is cleared. See capabili‐
131 ties(7).
132 * The termination signal is reset to SIGCHLD (see clone(2)).
134 * The file descriptor table is unshared, undoing the effect of the
136 CLONE_FILES flag of clone(2).
137 Note the following further points:
139 * All threads other than the calling thread are destroyed during an
141 execve(). Mutexes, condition variables, and other pthreads objects
142 are not preserved.
143 * The equivalent of setlocale(LC_ALL, "C") is executed at program
145 start-up.
146 * POSIX.1 specifies that the dispositions of any signals that are
148 ignored or set to the default are left unchanged. POSIX.1 specifies
149 one exception: if SIGCHLD is being ignored, then an implementation
150 may leave the disposition unchanged or reset it to the default;
151 Linux does the former.
152 * Any outstanding asynchronous I/O operations are canceled
154 (aio_read(3), aio_write(3)).
155 * For the handling of capabilities during execve(), see capabili‐
157 ties(7).
158 * By default, file descriptors remain open across an execve(). File
160 descriptors that are marked close-on-exec are closed; see the
161 description of FD_CLOEXEC in fcntl(2). (If a file descriptor is
162 closed, this will cause the release of all record locks obtained on
163 the underlying file by this process. See fcntl(2) for details.)
164 POSIX.1 says that if file descriptors 0, 1, and 2 would otherwise be
165 closed after a successful execve(), and the process would gain priv‐
166 ilege because the set-user-ID or set-group_ID mode bit was set on
167 the executed file, then the system may open an unspecified file for
168 each of these file descriptors. As a general principle, no portable
169 program, whether privileged or not, can assume that these three file
170 descriptors will remain closed across an execve().
171 Interpreter scripts
173 An interpreter script is a text file that has execute permission
174 enabled and whose first line is of the form:
175 #! interpreter [optional-arg]
177 The interpreter must be a valid pathname for an executable file. If
179 the filename argument of execve() specifies an interpreter script, then
180 interpreter will be invoked with the following arguments:
181 interpreter [optional-arg] filename arg...
183 where arg... is the series of words pointed to by the argv argument of
185 execve(), starting at argv[1].
186 For portable use, optional-arg should either be absent, or be specified
188 as a single word (i.e., it should not contain white space); see NOTES
189 below.
190 Since Linux 2.6.28, the kernel permits the interpreter of a script to
192 itself be a script. This permission is recursive, up to a limit of
193 four recursions, so that the interpreter may be a script which is
194 interpreted by a script, and so on.
195 Limits on size of arguments and environment
197 Most UNIX implementations impose some limit on the total size of the
198 command-line argument (argv) and environment (envp) strings that may be
199 passed to a new program. POSIX.1 allows an implementation to advertise
200 this limit using the ARG_MAX constant (either defined in <limits.h> or
201 available at run time using the call sysconf(_SC_ARG_MAX)).
202 On Linux prior to kernel 2.6.23, the memory used to store the environ‐
204 ment and argument strings was limited to 32 pages (defined by the ker‐
205 nel constant MAX_ARG_PAGES). On architectures with a 4-kB page size,
206 this yields a maximum size of 128 kB.
207 On kernel 2.6.23 and later, most architectures support a size limit
209 derived from the soft RLIMIT_STACK resource limit (see getrlimit(2))
210 that is in force at the time of the execve() call. (Architectures with
211 no memory management unit are excepted: they maintain the limit that
212 was in effect before kernel 2.6.23.) This change allows programs to
213 have a much larger argument and/or environment list. For these archi‐
214 tectures, the total size is limited to 1/4 of the allowed stack size.
215 (Imposing the 1/4-limit ensures that the new program always has some
216 stack space.) Since Linux 2.6.25, the kernel places a floor of 32
217 pages on this size limit, so that, even when RLIMIT_STACK is set very
218 low, applications are guaranteed to have at least as much argument and
219 environment space as was provided by Linux 2.6.23 and earlier. (This
220 guarantee was not provided in Linux 2.6.23 and 2.6.24.) Additionally,
221 the limit per string is 32 pages (the kernel constant MAX_ARG_STRLEN),
222 and the maximum number of strings is 0x7FFFFFFF.
223
225 On success, execve() does not return, on error -1 is returned, and
226 errno is set appropriately.
227
229 E2BIG The total number of bytes in the environment (envp) and argument
230 list (argv) is too large.
231 EACCES Search permission is denied on a component of the path prefix of
233 filename or the name of a script interpreter. (See also
234 path_resolution(7).)
235 EACCES The file or a script interpreter is not a regular file.
237 EACCES Execute permission is denied for the file or a script or ELF
239 interpreter.
240 EACCES The filesystem is mounted noexec.
242 EAGAIN (since Linux 3.1)
244 Having changed its real UID using one of the set*uid() calls,
245 the caller was—and is now still—above its RLIMIT_NPROC resource
246 limit (see setrlimit(2)). For a more detailed explanation of
247 this error, see NOTES.
248 EFAULT filename or one of the pointers in the vectors argv or envp
250 points outside your accessible address space.
251 EINVAL An ELF executable had more than one PT_INTERP segment (i.e.,
253 tried to name more than one interpreter).
254 EIO An I/O error occurred.
256 EISDIR An ELF interpreter was a directory.
258 ELIBBAD
260 An ELF interpreter was not in a recognized format.
261 ELOOP Too many symbolic links were encountered in resolving filename
263 or the name of a script or ELF interpreter.
264 ELOOP The maximum recursion limit was reached during recursive script
266 interpretation (see "Interpreter scripts", above). Before Linux
267 3.8, the error produced for this case was ENOEXEC.
268 EMFILE The per-process limit on the number of open file descriptors has
270 been reached.
271 ENAMETOOLONG
273 filename is too long.
274 ENFILE The system-wide limit on the total number of open files has been
276 reached.
277 ENOENT The file filename or a script or ELF interpreter does not exist,
279 or a shared library needed for the file or interpreter cannot be
280 found.
281 ENOEXEC
283 An executable is not in a recognized format, is for the wrong
284 architecture, or has some other format error that means it can‐
285 not be executed.
286 ENOMEM Insufficient kernel memory was available.
288 ENOTDIR
290 A component of the path prefix of filename or a script or ELF
291 interpreter is not a directory.
292 EPERM The filesystem is mounted nosuid, the user is not the superuser,
294 and the file has the set-user-ID or set-group-ID bit set.
295 EPERM The process is being traced, the user is not the superuser and
297 the file has the set-user-ID or set-group-ID bit set.
298 EPERM A "capability-dumb" applications would not obtain the full set
300 of permitted capabilities granted by the executable file. See
301 capabilities(7).
302 ETXTBSY
304 The specified executable was open for writing by one or more
305 processes.
306
308 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. POSIX does not document the
309 #! behavior, but it exists (with some variations) on other UNIX sys‐
310 tems.
311
313 Set-user-ID and set-group-ID processes can not be ptrace(2)d.
314 The result of mounting a filesystem nosuid varies across Linux kernel
316 versions: some will refuse execution of set-user-ID and set-group-ID
317 executables when this would give the user powers she did not have
318 already (and return EPERM), some will just ignore the set-user-ID and
319 set-group-ID bits and exec() successfully.
320 On Linux, argv and envp can be specified as NULL. In both cases, this
322 has the same effect as specifying the argument as a pointer to a list
323 containing a single null pointer. Do not take advantage of this non‐
324 standard and nonportable misfeature! On many other UNIX systems, spec‐
325 ifying argv as NULL will result in an error (EFAULT). Some other UNIX
326 systems treat the envp==NULL case the same as Linux.
327 POSIX.1 says that values returned by sysconf(3) should be invariant
329 over the lifetime of a process. However, since Linux 2.6.23, if the
330 RLIMIT_STACK resource limit changes, then the value reported by
331 _SC_ARG_MAX will also change, to reflect the fact that the limit on
332 space for holding command-line arguments and environment variables has
333 changed.
334 In most cases where execve() fails, control returns to the original
336 executable image, and the caller of execve() can then handle the error.
337 However, in (rare) cases (typically caused by resource exhaustion),
338 failure may occur past the point of no return: the original executable
339 image has been torn down, but the new image could not be completely
340 built. In such cases, the kernel kills the process with a SIGKILL sig‐
341 nal.
342 Interpreter scripts
344 A maximum line length of 127 characters is allowed for the first line
345 in an interpreter script.
346 The semantics of the optional-arg argument of an interpreter script
348 vary across implementations. On Linux, the entire string following the
349 interpreter name is passed as a single argument to the interpreter, and
350 this string can include white space. However, behavior differs on some
351 other systems. Some systems use the first white space to terminate
352 optional-arg. On some systems, an interpreter script can have multiple
353 arguments, and white spaces in optional-arg are used to delimit the
354 arguments.
355 Linux ignores the set-user-ID and set-group-ID bits on scripts.
357 execve() and EAGAIN
359 A more detailed explanation of the EAGAIN error that can occur (since
360 Linux 3.1) when calling execve() is as follows.
361 The EAGAIN error can occur when a preceding call to setuid(2),
363 setreuid(2), or setresuid(2) caused the real user ID of the process to
364 change, and that change caused the process to exceed its RLIMIT_NPROC
365 resource limit (i.e., the number of processes belonging to the new real
366 UID exceeds the resource limit). From Linux 2.6.0 to 3.0, this caused
367 the set*uid() call to fail. (Prior to 2.6, the resource limit was not
368 imposed on processes that changed their user IDs.)
369 Since Linux 3.1, the scenario just described no longer causes the
371 set*uid() call to fail, because it too often led to security holes
372 where buggy applications didn't check the return status and assumed
373 that—if the caller had root privileges—the call would always succeed.
374 Instead, the set*uid() calls now successfully change the real UID, but
375 the kernel sets an internal flag, named PF_NPROC_EXCEEDED, to note that
376 the RLIMIT_NPROC resource limit has been exceeded. If the
377 PF_NPROC_EXCEEDED flag is set and the resource limit is still exceeded
378 at the time of a subsequent execve() call, that call fails with the
379 error EAGAIN. This kernel logic ensures that the RLIMIT_NPROC resource
380 limit is still enforced for the common privileged daemon workflow—
381 namely, fork(2) + set*uid() + execve().
382 If the resource limit was not still exceeded at the time of the
384 execve() call (because other processes belonging to this real UID ter‐
385 minated between the set*uid() call and the execve() call), then the
386 execve() call succeeds and the kernel clears the PF_NPROC_EXCEEDED
387 process flag. The flag is also cleared if a subsequent call to fork(2)
388 by this process succeeds.
389 Historical
391 With UNIX V6, the argument list of an exec() call was ended by 0, while
392 the argument list of main was ended by -1. Thus, this argument list
393 was not directly usable in a further exec() call. Since UNIX V7, both
394 are NULL.
395
397 The following program is designed to be execed by the second program
398 below. It just echoes its command-line arguments, one per line.
399 /* myecho.c */
401 #include <stdio.h>
403 #include <stdlib.h>
404 int
406 main(int argc, char *argv[])
407 {
408 int j;
409 for (j = 0; j < argc; j++)
411 printf("argv[%d]: %s\n", j, argv[j]);
412 exit(EXIT_SUCCESS);
414 }
415 This program can be used to exec the program named in its command-line
417 argument:
418 /* execve.c */
420 #include <stdio.h>
422 #include <stdlib.h>
423 #include <unistd.h>
424 int
426 main(int argc, char *argv[])
427 {
428 char *newargv[] = { NULL, "hello", "world", NULL };
429 char *newenviron[] = { NULL };
430 if (argc != 2) {
432 fprintf(stderr, "Usage: %s <file-to-exec>\n", argv[0]);
433 exit(EXIT_FAILURE);
434 }
435 newargv[0] = argv[1];
437 execve(argv[1], newargv, newenviron);
439 perror("execve"); /* execve() returns only on error */
440 exit(EXIT_FAILURE);
441 }
442 We can use the second program to exec the first as follows:
444 $ cc myecho.c -o myecho
446 $ cc execve.c -o execve
447 $ ./execve ./myecho
448 argv[0]: ./myecho
449 argv[1]: hello
450 argv[2]: world
451 We can also use these programs to demonstrate the use of a script
453 interpreter. To do this we create a script whose "interpreter" is our
454 myecho program:
455 $ cat > script
457 #!./myecho script-arg
458 ^D
459 $ chmod +x script
460 We can then use our program to exec the script:
462 $ ./execve ./script
464 argv[0]: ./myecho
465 argv[1]: script-arg
466 argv[2]: ./script
467 argv[3]: hello
468 argv[4]: world
469
471 chmod(2), execveat(2), fork(2), get_robust_list(2), ptrace(2),
472 execl(3), fexecve(3), getopt(3), system(3), credentials(7), environ(7),
473 path_resolution(7), ld.so(8)
474
476 This page is part of release 4.15 of the Linux man-pages project. A
477 description of the project, information about reporting bugs, and the
478 latest version of this page, can be found at
479 https://www.kernel.org/doc/man-pages/.
480Linux 2017-09-15 EXECVE(2)