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