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