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