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