1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
4 .\" and Copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
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>
31 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
32 .\" 2006-09-04 Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" Added list of process attributes that are not preserved on exec().
34 .\" 2007-09-14 Ollie Wild <aaw@google.com>, mtk
35 .\" Add text describing limits on command-line arguments + environment
37 .TH EXECVE 2 2010-01-06 "Linux" "Linux Programmer's Manual"
39 execve \- execute program
41 .B #include <unistd.h>
43 .BI "int execve(const char *" filename ", char *const " argv "[], "
45 .BI " char *const " envp []);
48 executes the program pointed to by \fIfilename\fP.
49 \fIfilename\fP must be either a binary executable, or a script
50 starting with a line of the form:
54 \fB#!\fP \fIinterpreter \fP[optional-arg]
58 For details of the latter case, see "Interpreter scripts" below.
60 \fIargv\fP is an array of argument strings passed to the new program.
61 \fIenvp\fP is an array of strings, conventionally of the form
62 \fBkey=value\fP, which are passed as environment to the new program.
63 Both \fIargv\fP and \fIenvp\fP must be terminated by a null pointer.
64 The argument vector and environment can be accessed by the
65 called program's main function, when it is defined as:
69 int main(int argc, char *argv[], char *envp[])
74 does not return on success, and the text, data, bss, and
75 stack of the calling process are overwritten by that of the program
78 If the current program is being ptraced, a \fBSIGTRAP\fP is sent to it
82 If the set-user-ID bit is set on the program file pointed to by
84 and the underlying file system is not mounted
90 and the calling process is not being ptraced,
91 then the effective user ID of the calling process is changed
92 to that of the owner of the program file.
93 Similarly, when the set-group-ID
94 bit of the program file is set the effective group ID of the calling
95 process is set to the group of the program file.
97 The effective user ID of the process is copied to the saved set-user-ID;
98 similarly, the effective group ID is copied to the saved set-group-ID.
99 This copying takes place after any effective ID changes that occur
100 because of the set-user-ID and set-group-ID permission bits.
102 If the executable is an a.out dynamically linked
103 binary executable containing
104 shared-library stubs, the Linux dynamic linker
106 is called at the start of execution to bring
107 needed shared libraries into memory
108 and link the executable with them.
110 If the executable is a dynamically linked ELF executable, the
111 interpreter named in the PT_INTERP segment is used to load the needed
113 This interpreter is typically
114 \fI/lib/ld-linux.so.1\fP for binaries linked with the
115 Linux libc 5, or \fI/lib/ld-linux.so.2\fP for binaries linked with the
118 All process attributes are preserved during an
120 except the following:
122 The dispositions of any signals that are being caught are
126 Any alternate signal stack is not preserved
127 .RB ( sigaltstack (2)).
129 Memory mappings are not preserved
132 Attached System V shared memory segments are detached
135 POSIX shared memory regions are unmapped
138 Open POSIX message queue descriptors are closed
139 .RB ( mq_overview (7)).
141 Any open POSIX named semaphores are closed
142 .RB ( sem_overview (7)).
144 POSIX timers are not preserved
145 .RB ( timer_create (2)).
147 Any open directory streams are closed
150 Memory locks are not preserved
154 Exit handlers are not preserved
158 The floating-point environment is reset to the default (see
161 The process attributes in the preceding list are all specified
163 The following Linux-specific process attributes are also
164 not preserved during an
171 unless a set-user-ID or set-group ID program is being executed,
172 in which case it is cleared.
179 The process name, as set by
183 .IR "ps\ \-o comm" ),
184 is reset to the name of the new executable file.
186 The termination signal is reset to
191 Note the following further points:
193 All threads other than the calling thread are destroyed during an
195 Mutexes, condition variables, and other pthreads objects are not preserved.
197 The equivalent of \fIsetlocale(LC_ALL, "C")\fP
198 is executed at program start-up.
200 POSIX.1-2001 specifies that the dispositions of any signals that
201 are ignored or set to the default are left unchanged.
202 POSIX.1-2001 specifies one exception: if
205 then an implementation may leave the disposition unchanged or
206 reset it to the default; Linux does the former.
208 Any outstanding asynchronous I/O operations are canceled
212 For the handling of capabilities during
215 .BR capabilities (7).
217 By default, file descriptors remain open across an
219 File descriptors that are marked close-on-exec are closed;
220 see the description of
224 (If a file descriptor is closed, this will cause the release
225 of all record locks obtained on the underlying file by this process.
229 POSIX.1-2001 says that if file descriptors 0, 1, and 2 would
230 otherwise be closed after a successful
232 and the process would gain privilege because the set-user_ID or
233 set-group_ID permission bit was set on the executed file,
234 then the system may open an unspecified file for each of these
236 As a general principle, no portable program, whether privileged or not,
237 can assume that these three file descriptors will remain
240 .\" On Linux it appears that these file descriptors are
241 .\" always open after an execve(), and it looks like
242 .\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007
243 .SS Interpreter scripts
244 An interpreter script is a text file that has execute
245 permission enabled and whose first line is of the form:
249 \fB#!\fP \fIinterpreter \fP[optional-arg]
255 must be a valid pathname for an
256 executable which is not itself a script.
261 specifies an interpreter script, then
263 will be invoked with the following arguments:
267 \fIinterpreter\fP [optional-arg] \fIfilename\fP arg...
273 is the series of words pointed to by the
280 should either be absent, or be specified as a single word (i.e., it
281 should not contain white space); see NOTES below.
282 .SS "Limits on size of arguments and environment"
283 Most Unix implementations impose some limit on the total size
284 of the command-line argument
288 strings that may be passed to a new program.
289 POSIX.1 allows an implementation to advertise this limit using the
291 constant (either defined in
293 or available at run time using the call
294 .IR "sysconf(_SC_ARG_MAX)" ).
296 On Linux prior to kernel 2.6.23, the memory used to store the
297 environment and argument strings was limited to 32 pages
298 (defined by the kernel constant
300 On architectures with a 4-kB page size,
301 this yields a maximum size of 128 kB.
303 On kernel 2.6.23 and later, most architectures support a size limit
304 derived from the soft
308 that is in force at the time of the
311 (Architectures with no memory management unit are excepted:
312 they maintain the limit that was in effect before kernel 2.6.23.)
313 This change allows programs to have a much larger
314 argument and/or environment list.
315 .\" For some background on the changes to ARG_MAX in kernels 2.6.23 and
317 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786
318 .\" http://bugzilla.kernel.org/show_bug.cgi?id=10095
319 .\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101,
320 .\" checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2.
321 For these architectures, the total size is limited to 1/4 of the allowed
323 (Imposing the 1/4-limit
324 ensures that the new program always has some stack space.)
325 .\" Ollie: That doesn't include the lists of pointers, though,
326 .\" so the actual usage is a bit higher (1 pointer per argument).
328 the kernel places a floor of 32 pages on this size limit,
332 applications are guaranteed to have at least as much argument and
333 environment space as was provided by Linux 2.6.23 and earlier.
334 (This guarantee was not provided in Linux 2.6.23 and 2.6.24.)
335 Additionally, the limit per string is 32 pages (the kernel constant
336 .BR MAX_ARG_STRLEN ),
337 and the maximum number of strings is 0x7FFFFFFF.
341 does not return, on error \-1 is returned, and
343 is set appropriately.
347 The total number of bytes in the environment
354 Search permission is denied on a component of the path prefix of
356 or the name of a script interpreter.
358 .BR path_resolution (7).)
361 The file or a script interpreter is not a regular file.
364 Execute permission is denied for the file or a script or ELF interpreter.
367 The file system is mounted
372 points outside your accessible address space.
375 An ELF executable had more than one PT_INTERP segment (i.e., tried to
376 name more than one interpreter).
379 An I/O error occurred.
382 An ELF interpreter was a directory.
385 An ELF interpreter was not in a recognized format.
388 Too many symbolic links were encountered in resolving
390 or the name of a script or ELF interpreter.
393 The process has the maximum number of files open.
400 The system limit on the total number of open files has been reached.
405 or a script or ELF interpreter does not exist, or a shared library
406 needed for file or interpreter cannot be found.
409 An executable is not in a recognized format, is for the wrong
410 architecture, or has some other format error that means it cannot be
414 Insufficient kernel memory was available.
417 A component of the path prefix of
419 or a script or ELF interpreter is not a directory.
422 The file system is mounted
424 the user is not the superuser,
425 and the file has the set-user-ID or set-group-ID bit set.
428 The process is being traced, the user is not the superuser and the
429 file has the set-user-ID or set-group-ID bit set.
432 Executable was open for writing by one or more processes.
434 SVr4, 4.3BSD, POSIX.1-2001.
435 POSIX.1-2001 does not document the #! behavior
436 but is otherwise compatible.
437 .\" SVr4 documents additional error
438 .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not
439 .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL,
440 .\" EISDIR or ELIBBAD error conditions.
442 Set-user-ID and set-group-ID processes can not be
445 Linux ignores the set-user-ID and set-group-ID bits on scripts.
447 The result of mounting a file system
449 varies across Linux kernel versions:
450 some will refuse execution of set-user-ID and set-group-ID
451 executables when this would
452 give the user powers she did not have already (and return
454 some will just ignore the set-user-ID and set-group-ID bits and
458 A maximum line length of 127 characters is allowed for the first line in
459 a #! executable shell script.
463 argument of an interpreter script vary across implementations.
464 On Linux, the entire string following the
466 name is passed as a single argument to the interpreter,
467 and this string can include white space.
468 However, behavior differs on some other systems.
471 use the first white space to terminate
474 .\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onwards
475 an interpreter script can have multiple arguments,
478 are used to delimit the arguments.
482 can be specified as NULL,
483 which has the same effect as specifying this argument
484 as a pointer to a list containing a single NULL pointer.
485 .B "Do not take advantage of this misfeature!"
486 It is nonstandard and non-portable:
487 on most other Unix systems doing this will result in an error
489 .\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but
490 .\" HP-UX 11 is like Linux -- mtk, Apr 2007
491 .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408
492 .\" Bug rejected (because fix would constitute an ABI change).
495 POSIX.1-2001 says that values returned by
497 should be invariant over the lifetime of a process.
498 However, since Linux 2.6.23, if the
500 resource limit changes, then the value reported by
503 to reflect the fact that the limit on space for holding
504 command-line arguments and environment variables has changed.
507 .\" Some Linux versions have failed to check permissions on ELF
508 .\" interpreters. This is a security hole, because it allows users to
509 .\" open any file, such as a rewinding tape device, for reading. Some
510 .\" Linux versions have also had other security holes in
512 .\" that could be exploited for denial of service by a suitably crafted
513 .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15.
515 With Unix V6 the argument list of an
518 while the argument list of
521 Thus, this argument list was not directly usable in a further
524 Since Unix V7 both are NULL.
526 The following program is designed to be execed by the second program below.
527 It just echoes its command-line one per line.
537 main(int argc, char *argv[])
541 for (j = 0; j < argc; j++)
542 printf("argv[%d]: %s\\n", j, argv[j]);
549 This program can be used to exec the program named in its command-line
561 main(int argc, char *argv[])
563 char *newargv[] = { NULL, "hello", "world", NULL };
564 char *newenviron[] = { NULL };
567 fprintf(stderr, "Usage: %s <file-to-exec>\\n", argv[0]);
571 newargv[0] = argv[1];
573 execve(argv[1], newargv, newenviron);
574 perror("execve"); /* execve() only returns on error */
580 We can use the second program to exec the first as follows:
584 .RB "$" " cc myecho.c \-o myecho"
585 .RB "$" " cc execve.c \-o execve"
586 .RB "$" " ./execve ./myecho"
593 We can also use these programs to demonstrate the use of a script
595 To do this we create a script whose "interpreter" is our
601 .RB "$" " cat > script.sh"
602 .B #! ./myecho script-arg
604 .RB "$" " chmod +x script.sh"
608 We can then use our program to exec the script:
612 .RB "$" " ./execve ./script.sh"
629 .BR path_resolution (7),