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