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 2008-10-04 "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 set of pending signals is cleared
123 .RB ( sigpending (2)).
125 The dispositions of any signals that are being caught are
126 reset to being ignored.
128 Any alternate signal stack is not preserved
129 .RB ( sigaltstack (2)).
131 Memory mappings are not preserved
134 Attached System V shared memory segments are detached
137 POSIX shared memory regions are unmapped
140 Open POSIX message queue descriptors are closed
141 .RB ( mq_overview (7)).
143 Any open POSIX named semaphores are closed
144 .RB ( sem_overview (7)).
146 POSIX timers are not preserved
147 .RB ( timer_create (3)).
149 Any open directory streams are closed
152 Memory locks are not preserved
156 Exit handlers are not preserved
160 The floating-point environment is reset to the default (see
163 The process attributes in the preceding list are all specified
165 The following Linux-specific process attributes are also
166 not preserved during an
173 unless a set-user-ID or set-group ID program is being executed,
174 in which case it is cleared.
181 The process name, as set by
185 .IR "ps\ \-o comm" ),
186 is reset to the name of the new executable file.
188 The termination signal is reset to
193 Note the following further points:
195 All threads other than the calling thread are destroyed during an
197 Mutexes, condition variables, and other pthreads objects are not preserved.
199 The equivalent of \fIsetlocale(LC_ALL, "C")\fP
200 is executed at program start-up.
202 POSIX.1-2001 specifies that the dispositions of any signals that
203 are ignored or set to the default are left unchanged.
204 POSIX.1-2001 specifies one exception: if
207 then an implementation may leave the disposition unchanged or
208 reset it to the default; Linux does the former.
210 Any outstanding asynchronous I/O operations are canceled
214 For the handling of capabilities during
217 .BR capabilities (7).
219 By default, file descriptors remain open across an
221 File descriptors that are marked close-on-exec are closed;
222 see the description of
226 (If a file descriptor is closed, this will cause the release
227 of all record locks obtained on the underlying file by this process.
231 POSIX.1-2001 says that if file descriptors 0, 1, and 2 would
232 otherwise be closed after a successful
234 and the process would gain privilege because the set-user_ID or
235 set-group_ID permission bit was set on the executed file,
236 then the system may open an unspecified file for each of these
238 As a general principle, no portable program, whether privileged or not,
239 can assume that these three file descriptors will remain
242 .\" On Linux it appears that these file descriptors are
243 .\" always open after an execve(), and it looks like
244 .\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007
245 .SS Interpreter scripts
246 An interpreter script is a text file that has execute
247 permission enabled and whose first line is of the form:
251 \fB#!\fP \fIinterpreter \fP[optional-arg]
257 must be a valid pathname for an
258 executable which is not itself a script.
263 specifies an interpreter script, then
265 will be invoked with the following arguments:
269 \fIinterpreter\fP [optional-arg] \fIfilename\fP arg...
275 is the series of words pointed to by the
282 should either be absent, or be specified as a single word (i.e., it
283 should not contain white space); see NOTES below.
284 .SS "Limits on size of arguments and environment"
285 Most Unix implementations impose some limit on the total size
286 of the command-line argument
290 strings that may be passed to a new program.
291 POSIX.1 allows an implementation to advertise this limit using the
293 constant (either defined in
295 or available at run time using the call
296 .IR "sysconf(_SC_ARG_MAX)" ).
298 On Linux prior to kernel 2.6.23, the memory used to store the
299 environment and argument strings was limited to 32 pages
300 (defined by the kernel constant
302 On architectures with a 4-kB page size,
303 this yields a maximum size of 128 kB.
305 On kernel 2.6.23 and later, most architectures support a size limit
306 derived from the soft
310 that is in force at the time of the
313 (Architectures with no memory management unit are excepted:
314 they maintain the limit that was in effect before kernel 2.6.23.)
315 This change allows programs to have a much larger
316 argument and/or environment list.
317 .\" For some background on the changes to ARG_MAX in kernels 2.6.23 and
319 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786
320 .\" http://bugzilla.kernel.org/show_bug.cgi?id=10095
321 .\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101,
322 .\" checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2.
323 For these architectures, the total size is limited to 1/4 of the allowed
325 (Imposing the 1/4-limit
326 ensures that the new program always has some stack space.)
327 .\" Ollie: That doesn't include the lists of pointers, though,
328 .\" so the actual usage is a bit higher (1 pointer per argument).
330 the kernel places a floor of 32 pages on this size limit,
334 applications are guaranteed to have at least as much argument and
335 environment space as was provided by Linux 2.6.23 and earlier.
336 (This guarantee was not provided in Linux 2.6.23 and 2.6.24.)
337 Additionally, the limit per string is 32 pages (the kernel constant
338 .BR MAX_ARG_STRLEN ),
339 and the maximum number of strings is 0x7FFFFFFF.
343 does not return, on error \-1 is returned, and
345 is set appropriately.
349 The total number of bytes in the environment
356 Search permission is denied on a component of the path prefix of
358 or the name of a script interpreter.
360 .BR path_resolution (7).)
363 The file or a script interpreter is not a regular file.
366 Execute permission is denied for the file or a script or ELF interpreter.
369 The file system is mounted
374 points outside your accessible address space.
377 An ELF executable had more than one PT_INTERP segment (i.e., tried to
378 name more than one interpreter).
381 An I/O error occurred.
384 An ELF interpreter was a directory.
387 An ELF interpreter was not in a recognized format.
390 Too many symbolic links were encountered in resolving
392 or the name of a script or ELF interpreter.
395 The process has the maximum number of files open.
402 The system limit on the total number of open files has been reached.
407 or a script or ELF interpreter does not exist, or a shared library
408 needed for file or interpreter cannot be found.
411 An executable is not in a recognized format, is for the wrong
412 architecture, or has some other format error that means it cannot be
416 Insufficient kernel memory was available.
419 A component of the path prefix of
421 or a script or ELF interpreter is not a directory.
424 The file system is mounted
426 the user is not the superuser,
427 and the file has the set-user-ID or set-group-ID bit set.
430 The process is being traced, the user is not the superuser and the
431 file has the set-user-ID or set-group-ID bit set.
434 Executable was open for writing by one or more processes.
436 SVr4, 4.3BSD, POSIX.1-2001.
437 POSIX.1-2001 does not document the #! behavior
438 but is otherwise compatible.
439 .\" SVr4 documents additional error
440 .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not
441 .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL,
442 .\" EISDIR or ELIBBAD error conditions.
444 Set-user-ID and set-group-ID processes can not be
447 Linux ignores the set-user-ID and set-group-ID bits on scripts.
449 The result of mounting a file system
451 varies across Linux kernel versions:
452 some will refuse execution of set-user-ID and set-group-ID
453 executables when this would
454 give the user powers she did not have already (and return
456 some will just ignore the set-user-ID and set-group-ID bits and
460 A maximum line length of 127 characters is allowed for the first line in
461 a #! executable shell script.
465 argument of an interpreter script vary across implementations.
466 On Linux, the entire string following the
468 name is passed as a single argument to the interpreter,
469 and this string can include white space.
470 However, behavior differs on some other systems.
473 use the first white space to terminate
476 .\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onwards
477 an interpreter script can have multiple arguments,
480 are used to delimit the arguments.
484 can be specified as NULL,
485 which has the same effect as specifying this argument
486 as a pointer to a list containing a single NULL pointer.
487 .B "Do not take advantage of this misfeature!"
488 It is non-standard and non-portable:
489 on most other Unix systems doing this will result in an error
491 .\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but
492 .\" HP-UX 11 is like Linux -- mtk, Apr 2007
493 .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408
494 .\" Bug rejected (because fix would constitute an ABI change).
497 POSIX.1-2001 says that values returned by
499 should be invariant over the lifetime of a process.
500 However, since Linux 2.6.23, if the
502 resource limit changes, then the value reported by
505 to reflect the fact that the limit on space for holding
506 command-line arguments and environment variables has changed.
509 .\" Some Linux versions have failed to check permissions on ELF
510 .\" interpreters. This is a security hole, because it allows users to
511 .\" open any file, such as a rewinding tape device, for reading. Some
512 .\" Linux versions have also had other security holes in
514 .\" that could be exploited for denial of service by a suitably crafted
515 .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15.
517 With Unix V6 the argument list of an
520 while the argument list of
523 Thus, this argument list was not directly usable in a further
526 Since Unix V7 both are NULL.
528 The following program is designed to be execed by the second program below.
529 It just echoes its command-line one per line.
539 main(int argc, char *argv[])
543 for (j = 0; j < argc; j++)
544 printf("argv[%d]: %s\\n", j, argv[j]);
551 This program can be used to exec the program named in its command-line
564 main(int argc, char *argv[])
566 char *newargv[] = { NULL, "hello", "world", NULL };
567 char *newenviron[] = { NULL };
569 assert(argc == 2); /* argv[1] identifies
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 $ cc myecho.c \-o myecho
585 $ cc execve.c \-o execve
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
602 #! ./myecho script-arg
608 We can then use our program to exec the script:
612 $ ./execve ./script.sh
629 .BR path_resolution (7),