man2/execve.2

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