]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
c11b1abf | 2 | .\" and Copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified by Michael Haardt <michael@moria.de> | |
27 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com>: | |
29 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
30 | .\" Modified 1999-11-12 by Urs Thuermann <urs@isnogud.escape.de> | |
c11b1abf MK |
31 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
32 | .\" 2006-09-04 Michael Kerrisk <mtk.manpages@gmail.com> | |
e6b33ad7 | 33 | .\" Added list of process attributes that are not preserved on exec(). |
d739f5f8 MK |
34 | .\" 2007-09-14 Ollie Wild <aaw@google.com>, mtk |
35 | .\" Add text describing limits on command-line arguments + environment | |
fea681da | 36 | .\" |
460495ca | 37 | .TH EXECVE 2 2015-08-08 "Linux" "Linux Programmer's Manual" |
fea681da MK |
38 | .SH NAME |
39 | execve \- execute program | |
40 | .SH SYNOPSIS | |
41 | .B #include <unistd.h> | |
42 | .sp | |
7fdcdf23 MK |
43 | .BI "int execve(const char *" filename ", char *const " argv "[], " |
44 | .br | |
45 | .BI " char *const " envp []); | |
fea681da | 46 | .SH DESCRIPTION |
60a90ecd MK |
47 | .BR execve () |
48 | executes the program pointed to by \fIfilename\fP. | |
fea681da | 49 | \fIfilename\fP must be either a binary executable, or a script |
cd24c687 MK |
50 | starting with a line of the form: |
51 | ||
088a639b | 52 | .in +4n |
cd24c687 | 53 | .nf |
a8d55537 | 54 | \fB#!\fP \fIinterpreter \fP[optional-arg] |
cd24c687 MK |
55 | .fi |
56 | .in | |
57 | ||
e6b33ad7 | 58 | For details of the latter case, see "Interpreter scripts" below. |
fea681da MK |
59 | |
60 | \fIargv\fP is an array of argument strings passed to the new program. | |
1e8a0add MK |
61 | By convention, the first of these strings should contain the filename |
62 | associated with the file being executed. | |
fea681da | 63 | \fIenvp\fP is an array of strings, conventionally of the form |
a8d55537 | 64 | \fBkey=value\fP, which are passed as environment to the new program. |
b437fdd9 | 65 | Both \fIargv\fP and \fIenvp\fP must be terminated by a null pointer. |
c13182ef | 66 | The argument vector and environment can be accessed by the |
cd24c687 MK |
67 | called program's main function, when it is defined as: |
68 | ||
088a639b | 69 | .in +4n |
cd24c687 | 70 | .nf |
a8d55537 | 71 | int main(int argc, char *argv[], char *envp[]) |
cd24c687 MK |
72 | .fi |
73 | .in | |
fea681da | 74 | |
60a90ecd MK |
75 | .BR execve () |
76 | does not return on success, and the text, data, bss, and | |
fea681da | 77 | stack of the calling process are overwritten by that of the program |
c13182ef | 78 | loaded. |
fea681da MK |
79 | |
80 | If the current program is being ptraced, a \fBSIGTRAP\fP is sent to it | |
60a90ecd MK |
81 | after a successful |
82 | .BR execve (). | |
fea681da | 83 | |
880f5b4b | 84 | If the set-user-ID bit is set on the program file pointed to by |
988db661 | 85 | \fIfilename\fP, |
9ee4a2b6 | 86 | and the underlying filesystem is not mounted |
0daa9e92 | 87 | .I nosuid |
d6f223a7 MK |
88 | (the |
89 | .B MS_NOSUID | |
90 | flag for | |
91 | .BR mount (2)), | |
92 | and the calling process is not being ptraced, | |
6aacaf94 | 93 | then the effective user ID of the calling process is changed |
ef0b8171 | 94 | to that of the owner of the program file. |
07b501d1 | 95 | Similarly, when the set-group-ID |
fea681da MK |
96 | bit of the program file is set the effective group ID of the calling |
97 | process is set to the group of the program file. | |
98 | ||
07b501d1 MK |
99 | The effective user ID of the process is copied to the saved set-user-ID; |
100 | similarly, the effective group ID is copied to the saved set-group-ID. | |
c13182ef | 101 | This copying takes place after any effective ID changes that occur |
ed948c28 | 102 | because of the set-user-ID and set-group-ID mode bits. |
07b501d1 | 103 | |
3f624b93 | 104 | If the executable is an a.out dynamically linked |
07b501d1 | 105 | binary executable containing |
fea681da MK |
106 | shared-library stubs, the Linux dynamic linker |
107 | .BR ld.so (8) | |
c13182ef | 108 | is called at the start of execution to bring |
43151de3 | 109 | needed shared objects into memory |
fea681da MK |
110 | and link the executable with them. |
111 | ||
3f624b93 | 112 | If the executable is a dynamically linked ELF executable, the |
fea681da | 113 | interpreter named in the PT_INTERP segment is used to load the needed |
43151de3 | 114 | shared objects. |
c13182ef | 115 | This interpreter is typically |
1941c8e7 | 116 | .I /lib/ld-linux.so.2 |
a82507ce | 117 | for binaries linked with glibc. |
80a34ae3 MK |
118 | |
119 | All process attributes are preserved during an | |
120 | .BR execve (), | |
121 | except the following: | |
7bf5c019 | 122 | .IP * 3 |
c13182ef | 123 | The dispositions of any signals that are being caught are |
9ec8f860 CW |
124 | reset to the default |
125 | .RB ( signal (7)). | |
e4158924 | 126 | .IP * |
80a34ae3 MK |
127 | Any alternate signal stack is not preserved |
128 | .RB ( sigaltstack (2)). | |
e4158924 | 129 | .IP * |
80a34ae3 MK |
130 | Memory mappings are not preserved |
131 | .RB ( mmap (2)). | |
e4158924 | 132 | .IP * |
efbfd7ec | 133 | Attached System\ V shared memory segments are detached |
80a34ae3 | 134 | .RB ( shmat (2)). |
e4158924 | 135 | .IP * |
80a34ae3 MK |
136 | POSIX shared memory regions are unmapped |
137 | .RB ( shm_open (3)). | |
e4158924 | 138 | .IP * |
80a34ae3 MK |
139 | Open POSIX message queue descriptors are closed |
140 | .RB ( mq_overview (7)). | |
e4158924 | 141 | .IP * |
80a34ae3 MK |
142 | Any open POSIX named semaphores are closed |
143 | .RB ( sem_overview (7)). | |
e4158924 | 144 | .IP * |
80a34ae3 | 145 | POSIX timers are not preserved |
804f03e6 | 146 | .RB ( timer_create (2)). |
e4158924 | 147 | .IP * |
80a34ae3 MK |
148 | Any open directory streams are closed |
149 | .RB ( opendir (3)). | |
e4158924 | 150 | .IP * |
80a34ae3 MK |
151 | Memory locks are not preserved |
152 | .RB ( mlock (2), | |
153 | .BR mlockall (2)). | |
e4158924 | 154 | .IP * |
80a34ae3 MK |
155 | Exit handlers are not preserved |
156 | .RB ( atexit (3), | |
157 | .BR on_exit (3)). | |
2fb19a16 MK |
158 | .IP * |
159 | The floating-point environment is reset to the default (see | |
160 | .BR fenv (3)). | |
80a34ae3 | 161 | .PP |
c13182ef | 162 | The process attributes in the preceding list are all specified |
ce1ff0f6 | 163 | in POSIX.1. |
c13182ef | 164 | The following Linux-specific process attributes are also |
80a34ae3 MK |
165 | not preserved during an |
166 | .BR execve (): | |
e4158924 | 167 | .IP * 3 |
c13182ef | 168 | The |
80a34ae3 | 169 | .BR prctl (2) |
c13182ef | 170 | .B PR_SET_DUMPABLE |
80a34ae3 MK |
171 | flag is set, |
172 | unless a set-user-ID or set-group ID program is being executed, | |
173 | in which case it is cleared. | |
e4158924 | 174 | .IP * |
c13182ef | 175 | The |
80a34ae3 MK |
176 | .BR prctl (2) |
177 | .B PR_SET_KEEPCAPS | |
178 | flag is cleared. | |
e4158924 | 179 | .IP * |
30cc7676 MK |
180 | (Since Linux 2.4.36 / 2.6.23) |
181 | If a set-user-ID or set-group-ID program is being executed, | |
182 | then the parent death signal set by | |
183 | .BR prctl (2) | |
184 | .B PR_SET_PDEATHSIG | |
185 | flag is cleared. | |
186 | .IP * | |
fe247268 MK |
187 | The process name, as set by |
188 | .BR prctl (2) | |
0daa9e92 | 189 | .B PR_SET_NAME |
fe247268 | 190 | (and displayed by |
80d26cef | 191 | .IR "ps\ \-o comm" ), |
fe247268 | 192 | is reset to the name of the new executable file. |
e4158924 | 193 | .IP * |
8e9412e7 MK |
194 | The |
195 | .B SECBIT_KEEP_CAPS | |
196 | .I securebits | |
197 | flag is cleared. | |
198 | See | |
199 | .BR capabilities (7). | |
200 | .IP * | |
8bd58774 MK |
201 | The termination signal is reset to |
202 | .B SIGCHLD | |
80a34ae3 MK |
203 | (see |
204 | .BR clone (2)). | |
8a76b19e KE |
205 | .IP * |
206 | The file descriptor table is unshared, undoing the effect of the | |
207 | .B CLONE_FILES | |
208 | flag of | |
209 | .BR clone (2). | |
80a34ae3 MK |
210 | .PP |
211 | Note the following further points: | |
e4158924 | 212 | .IP * 3 |
7fd8a3c9 | 213 | All threads other than the calling thread are destroyed during an |
80a34ae3 MK |
214 | .BR execve (). |
215 | Mutexes, condition variables, and other pthreads objects are not preserved. | |
e4158924 | 216 | .IP * |
80a34ae3 MK |
217 | The equivalent of \fIsetlocale(LC_ALL, "C")\fP |
218 | is executed at program start-up. | |
e4158924 | 219 | .IP * |
ce1ff0f6 | 220 | POSIX.1 specifies that the dispositions of any signals that |
80a34ae3 | 221 | are ignored or set to the default are left unchanged. |
ce1ff0f6 | 222 | POSIX.1 specifies one exception: if |
8bd58774 MK |
223 | .B SIGCHLD |
224 | is being ignored, | |
c13182ef | 225 | then an implementation may leave the disposition unchanged or |
80a34ae3 | 226 | reset it to the default; Linux does the former. |
e4158924 | 227 | .IP * |
d9bfdb9c | 228 | Any outstanding asynchronous I/O operations are canceled |
80a34ae3 MK |
229 | .RB ( aio_read (3), |
230 | .BR aio_write (3)). | |
e4158924 | 231 | .IP * |
c13182ef | 232 | For the handling of capabilities during |
2777b1ca | 233 | .BR execve (), |
80a34ae3 MK |
234 | see |
235 | .BR capabilities (7). | |
e4158924 | 236 | .IP * |
988db661 | 237 | By default, file descriptors remain open across an |
d6f223a7 | 238 | .BR execve (). |
3a16ac7a MK |
239 | File descriptors that are marked close-on-exec are closed; |
240 | see the description of | |
0daa9e92 | 241 | .B FD_CLOEXEC |
d6f223a7 MK |
242 | in |
243 | .BR fcntl (2). | |
244 | (If a file descriptor is closed, this will cause the release | |
245 | of all record locks obtained on the underlying file by this process. | |
246 | See | |
247 | .BR fcntl (2) | |
248 | for details.) | |
ce1ff0f6 | 249 | POSIX.1 says that if file descriptors 0, 1, and 2 would |
d6f223a7 MK |
250 | otherwise be closed after a successful |
251 | .BR execve (), | |
252 | and the process would gain privilege because the set-user_ID or | |
ed948c28 | 253 | set-group_ID mode bit was set on the executed file, |
d6f223a7 MK |
254 | then the system may open an unspecified file for each of these |
255 | file descriptors. | |
256 | As a general principle, no portable program, whether privileged or not, | |
988db661 | 257 | can assume that these three file descriptors will remain |
d6f223a7 MK |
258 | closed across an |
259 | .BR execve (). | |
260 | .\" On Linux it appears that these file descriptors are | |
261 | .\" always open after an execve(), and it looks like | |
262 | .\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007 | |
e6b33ad7 | 263 | .SS Interpreter scripts |
988db661 | 264 | An interpreter script is a text file that has execute |
e6b33ad7 MK |
265 | permission enabled and whose first line is of the form: |
266 | ||
088a639b | 267 | .in +4n |
e6b33ad7 | 268 | .nf |
a8d55537 | 269 | \fB#!\fP \fIinterpreter \fP[optional-arg] |
e6b33ad7 MK |
270 | .fi |
271 | .in | |
272 | ||
988db661 MK |
273 | The |
274 | .I interpreter | |
e6b33ad7 MK |
275 | must be a valid pathname for an |
276 | executable which is not itself a script. | |
988db661 | 277 | If the |
e6b33ad7 MK |
278 | .I filename |
279 | argument of | |
280 | .BR execve () | |
988db661 | 281 | specifies an interpreter script, then |
e6b33ad7 MK |
282 | .I interpreter |
283 | will be invoked with the following arguments: | |
284 | ||
088a639b | 285 | .in +4n |
e6b33ad7 | 286 | .nf |
a8d55537 | 287 | \fIinterpreter\fP [optional-arg] \fIfilename\fP arg... |
e6b33ad7 MK |
288 | .fi |
289 | .in | |
290 | ||
291 | where | |
292 | .I arg... | |
988db661 | 293 | is the series of words pointed to by the |
e6b33ad7 | 294 | .I argv |
988db661 | 295 | argument of |
a2954fe6 MK |
296 | .BR execve (), |
297 | starting at | |
298 | .IR argv [1]. | |
e6b33ad7 MK |
299 | |
300 | For portable use, | |
301 | .I optional-arg | |
302 | should either be absent, or be specified as a single word (i.e., it | |
303 | should not contain white space); see NOTES below. | |
73d8cece | 304 | .SS Limits on size of arguments and environment |
008f1ecc | 305 | Most UNIX implementations impose some limit on the total size |
d739f5f8 MK |
306 | of the command-line argument |
307 | .RI ( argv ) | |
308 | and environment | |
309 | .RI ( envp ) | |
310 | strings that may be passed to a new program. | |
311 | POSIX.1 allows an implementation to advertise this limit using the | |
0daa9e92 | 312 | .B ARG_MAX |
d739f5f8 MK |
313 | constant (either defined in |
314 | .I <limits.h> | |
315 | or available at run time using the call | |
316 | .IR "sysconf(_SC_ARG_MAX)" ). | |
317 | ||
318 | On Linux prior to kernel 2.6.23, the memory used to store the | |
319 | environment and argument strings was limited to 32 pages | |
320 | (defined by the kernel constant | |
321 | .BR MAX_ARG_PAGES ). | |
322 | On architectures with a 4-kB page size, | |
323 | this yields a maximum size of 128 kB. | |
324 | ||
325 | On kernel 2.6.23 and later, most architectures support a size limit | |
326 | derived from the soft | |
327 | .B RLIMIT_STACK | |
328 | resource limit (see | |
e5a7fca5 MK |
329 | .BR getrlimit (2)) |
330 | that is in force at the time of the | |
331 | .BR execve () | |
332 | call. | |
f202015b MK |
333 | (Architectures with no memory management unit are excepted: |
334 | they maintain the limit that was in effect before kernel 2.6.23.) | |
335 | This change allows programs to have a much larger | |
d739f5f8 | 336 | argument and/or environment list. |
f202015b MK |
337 | .\" For some background on the changes to ARG_MAX in kernels 2.6.23 and |
338 | .\" 2.6.25, see: | |
339 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786 | |
340 | .\" http://bugzilla.kernel.org/show_bug.cgi?id=10095 | |
341 | .\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, | |
342 | .\" checked into 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. | |
343 | For these architectures, the total size is limited to 1/4 of the allowed | |
344 | stack size. | |
345 | (Imposing the 1/4-limit | |
d739f5f8 | 346 | ensures that the new program always has some stack space.) |
d739f5f8 MK |
347 | .\" Ollie: That doesn't include the lists of pointers, though, |
348 | .\" so the actual usage is a bit higher (1 pointer per argument). | |
f202015b MK |
349 | Since Linux 2.6.25, |
350 | the kernel places a floor of 32 pages on this size limit, | |
351 | so that, even when | |
352 | .BR RLIMIT_STACK | |
353 | is set very low, | |
354 | applications are guaranteed to have at least as much argument and | |
355 | environment space as was provided by Linux 2.6.23 and earlier. | |
356 | (This guarantee was not provided in Linux 2.6.23 and 2.6.24.) | |
357 | Additionally, the limit per string is 32 pages (the kernel constant | |
358 | .BR MAX_ARG_STRLEN ), | |
359 | and the maximum number of strings is 0x7FFFFFFF. | |
47297adb | 360 | .SH RETURN VALUE |
60a90ecd MK |
361 | On success, |
362 | .BR execve () | |
363 | does not return, on error \-1 is returned, and | |
fea681da MK |
364 | .I errno |
365 | is set appropriately. | |
366 | .SH ERRORS | |
367 | .TP | |
368 | .B E2BIG | |
c13182ef | 369 | The total number of bytes in the environment |
4989c2f3 | 370 | .RI ( envp ) |
c13182ef | 371 | and argument list |
4989c2f3 MK |
372 | .RI ( argv ) |
373 | is too large. | |
fea681da MK |
374 | .TP |
375 | .B EACCES | |
376 | Search permission is denied on a component of the path prefix of | |
377 | .I filename | |
378 | or the name of a script interpreter. | |
379 | (See also | |
ad7cc990 | 380 | .BR path_resolution (7).) |
fea681da MK |
381 | .TP |
382 | .B EACCES | |
383 | The file or a script interpreter is not a regular file. | |
384 | .TP | |
385 | .B EACCES | |
386 | Execute permission is denied for the file or a script or ELF interpreter. | |
387 | .TP | |
388 | .B EACCES | |
9ee4a2b6 | 389 | The filesystem is mounted |
fea681da MK |
390 | .IR noexec . |
391 | .TP | |
ebd381ba MK |
392 | .BR EAGAIN " (since Linux 3.1)" |
393 | .\" commit 72fa59970f8698023045ab0713d66f3f4f96945c | |
394 | Having changed its real UID using one of the | |
395 | .BR set*uid () | |
396 | calls, the caller was\(emand is now still\(emabove its | |
397 | .BR RLIMIT_NPROC | |
398 | resource limit (see | |
399 | .BR setrlimit (2)). | |
400 | For a more detailed explanation of this error, see NOTES. | |
401 | .TP | |
fea681da MK |
402 | .B EFAULT |
403 | .I filename | |
30410190 MK |
404 | or one of the pointers in the vectors |
405 | .I argv | |
406 | or | |
407 | .I envp | |
fea681da MK |
408 | points outside your accessible address space. |
409 | .TP | |
410 | .B EINVAL | |
411 | An ELF executable had more than one PT_INTERP segment (i.e., tried to | |
412 | name more than one interpreter). | |
413 | .TP | |
414 | .B EIO | |
415 | An I/O error occurred. | |
416 | .TP | |
417 | .B EISDIR | |
418 | An ELF interpreter was a directory. | |
419 | .TP | |
420 | .B ELIBBAD | |
d9bfdb9c | 421 | An ELF interpreter was not in a recognized format. |
fea681da MK |
422 | .TP |
423 | .B ELOOP | |
424 | Too many symbolic links were encountered in resolving | |
425 | .I filename | |
426 | or the name of a script or ELF interpreter. | |
427 | .TP | |
428 | .B EMFILE | |
429 | The process has the maximum number of files open. | |
430 | .TP | |
431 | .B ENAMETOOLONG | |
432 | .I filename | |
433 | is too long. | |
434 | .TP | |
435 | .B ENFILE | |
436 | The system limit on the total number of open files has been reached. | |
437 | .TP | |
438 | .B ENOENT | |
c13182ef | 439 | The file |
fea681da MK |
440 | .I filename |
441 | or a script or ELF interpreter does not exist, or a shared library | |
0b4ac988 | 442 | .\" FIXME but see http://sourceware.org/bugzilla/show_bug.cgi?id=12241 |
fea681da MK |
443 | needed for file or interpreter cannot be found. |
444 | .TP | |
445 | .B ENOEXEC | |
d9bfdb9c | 446 | An executable is not in a recognized format, is for the wrong |
fea681da MK |
447 | architecture, or has some other format error that means it cannot be |
448 | executed. | |
449 | .TP | |
450 | .B ENOMEM | |
451 | Insufficient kernel memory was available. | |
452 | .TP | |
453 | .B ENOTDIR | |
454 | A component of the path prefix of | |
455 | .I filename | |
456 | or a script or ELF interpreter is not a directory. | |
457 | .TP | |
458 | .B EPERM | |
9ee4a2b6 | 459 | The filesystem is mounted |
fea681da | 460 | .IR nosuid , |
c13182ef | 461 | the user is not the superuser, |
81069819 | 462 | and the file has the set-user-ID or set-group-ID bit set. |
fea681da MK |
463 | .TP |
464 | .B EPERM | |
465 | The process is being traced, the user is not the superuser and the | |
81069819 | 466 | file has the set-user-ID or set-group-ID bit set. |
fea681da MK |
467 | .TP |
468 | .B ETXTBSY | |
469 | Executable was open for writing by one or more processes. | |
47297adb | 470 | .SH CONFORMING TO |
ce1ff0f6 | 471 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
c95f9f2c MK |
472 | POSIX does not document the #! behavior, but it exists |
473 | (with some variations) on other UNIX systems. | |
97c1eac8 MK |
474 | .\" SVr4 documents additional error |
475 | .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not | |
476 | .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, | |
477 | .\" EISDIR or ELIBBAD error conditions. | |
fea681da | 478 | .SH NOTES |
0bfa087b MK |
479 | Set-user-ID and set-group-ID processes can not be |
480 | .BR ptrace (2)d. | |
fea681da | 481 | |
9ee4a2b6 | 482 | The result of mounting a filesystem |
fea681da | 483 | .I nosuid |
d6f223a7 | 484 | varies across Linux kernel versions: |
c13182ef | 485 | some will refuse execution of set-user-ID and set-group-ID |
81069819 | 486 | executables when this would |
682edefb MK |
487 | give the user powers she did not have already (and return |
488 | .BR EPERM ), | |
c13182ef | 489 | some will just ignore the set-user-ID and set-group-ID bits and |
1e321034 MK |
490 | .BR exec () |
491 | successfully. | |
09754758 | 492 | |
e6bec78c | 493 | On Linux, |
45696074 | 494 | .I argv |
e6bec78c | 495 | and |
0c42642f | 496 | .I envp |
e6bec78c MK |
497 | can be specified as NULL. |
498 | In both cases, this has the same effect as specifying the argument | |
b437fdd9 | 499 | as a pointer to a list containing a single null pointer. |
eb24aedc MK |
500 | .B "Do not take advantage of this nonstandard and nonportable misfeature!" |
501 | On many other UNIX systems, specifying | |
502 | .I argv | |
503 | as NULL will result in an error | |
34dcae54 | 504 | .RB ( EFAULT ). |
eb24aedc MK |
505 | .I Some |
506 | other UNIX systems treat the | |
507 | .I envp==NULL | |
508 | case the same as Linux. | |
75b94dc3 | 509 | .\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but |
45696074 | 510 | .\" HP-UX 11 is like Linux -- mtk, Apr 2007 |
45696074 | 511 | .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 |
bf501102 | 512 | .\" Bug rejected (because fix would constitute an ABI change). |
45696074 | 513 | .\" |
3a9dc9ff | 514 | |
ce1ff0f6 | 515 | POSIX.1 says that values returned by |
3a9dc9ff MK |
516 | .BR sysconf (3) |
517 | should be invariant over the lifetime of a process. | |
518 | However, since Linux 2.6.23, if the | |
519 | .BR RLIMIT_STACK | |
520 | resource limit changes, then the value reported by | |
521 | .B _SC_ARG_MAX | |
522 | will also change, | |
523 | to reflect the fact that the limit on space for holding | |
524 | command-line arguments and environment variables has changed. | |
3a4b02b2 MK |
525 | |
526 | In most cases where | |
527 | .BR execve () | |
528 | fails, control returns to the original executable image, | |
529 | and the caller of | |
530 | .BR execve () | |
531 | can then handle the error. | |
532 | However, in (rare) cases (typically caused by resource exhaustion), | |
533 | failure may occur past the point of no return: | |
534 | the original executable image has been torn down, | |
535 | but the new image could not be completely built. | |
536 | In such cases, the kernel kills the process with a | |
537 | .BR SIGKILL | |
538 | signal. | |
4c4d30d8 MK |
539 | .\" |
540 | .SS Interpreter scripts | |
541 | A maximum line length of 127 characters is allowed for the first line in | |
046d38ac | 542 | an interpreter scripts. |
4c4d30d8 MK |
543 | |
544 | The semantics of the | |
545 | .I optional-arg | |
546 | argument of an interpreter script vary across implementations. | |
547 | On Linux, the entire string following the | |
548 | .I interpreter | |
549 | name is passed as a single argument to the interpreter, | |
550 | and this string can include white space. | |
551 | However, behavior differs on some other systems. | |
552 | Some systems | |
553 | .\" e.g., Solaris 8 | |
554 | use the first white space to terminate | |
555 | .IR optional-arg . | |
556 | On some systems, | |
557 | .\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onward | |
558 | an interpreter script can have multiple arguments, | |
559 | and white spaces in | |
560 | .I optional-arg | |
561 | are used to delimit the arguments. | |
562 | ||
563 | Linux ignores the set-user-ID and set-group-ID bits on scripts. | |
564 | .\" | |
ebd381ba MK |
565 | .\" .SH BUGS |
566 | .\" Some Linux versions have failed to check permissions on ELF | |
567 | .\" interpreters. This is a security hole, because it allows users to | |
568 | .\" open any file, such as a rewinding tape device, for reading. Some | |
569 | .\" Linux versions have also had other security holes in | |
570 | .\" .BR execve () | |
571 | .\" that could be exploited for denial of service by a suitably crafted | |
572 | .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. | |
573 | .SS execve() and EAGAIN | |
574 | A more detailed explanation of the | |
575 | .BR EAGAIN | |
576 | error that can occur (since Linux 3.1) when calling | |
577 | .BR execve () | |
578 | is as follows. | |
579 | ||
580 | The | |
581 | .BR EAGAIN | |
582 | error can occur when a | |
583 | .I preceding | |
584 | call to | |
585 | .BR setuid (2), | |
586 | .BR setreuid (2), | |
587 | or | |
588 | .BR setresuid (2) | |
589 | caused the real user ID of the process to change, | |
590 | and that change caused the process to exceed its | |
591 | .BR RLIMIT_NPROC | |
592 | resource limit (i.e., the number of processes belonging | |
593 | to the new real UID exceeds the resource limit). | |
83490231 | 594 | From Linux 2.6.0 to 3.0, this caused the |
ebd381ba MK |
595 | .BR set*uid () |
596 | call to fail. | |
83490231 MK |
597 | (Prior to 2.6, |
598 | .\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 | |
599 | the resource limit was not imposed on processes that | |
600 | changed their user IDs.) | |
ebd381ba MK |
601 | |
602 | Since Linux 3.1, the scenario just described no longer causes the | |
603 | .BR set*uid () | |
604 | call to fail, | |
605 | because it too often led to security holes where buggy applications | |
606 | didn't check the return status and assumed | |
607 | that\(emif the caller had root privileges\(emthe call would always succeed. | |
608 | Instead, the | |
609 | .BR set*uid () | |
610 | calls now successfully change the real UID, | |
611 | but the kernel sets an internal flag, named | |
612 | .BR PF_NPROC_EXCEEDED , | |
613 | to note that the | |
614 | .BR RLIMIT_NPROC | |
615 | resource limit has been exceeded. | |
adab861a MK |
616 | If the |
617 | .BR PF_NPROC_EXCEEDED | |
618 | flag is set and the resource limit is still | |
619 | exceeded at the time of a subsequent | |
ebd381ba MK |
620 | .BR execve () |
621 | call, that call fails with the error | |
622 | .BR EAGAIN . | |
623 | This kernel logic ensures that the | |
624 | .BR RLIMIT_NPROC | |
625 | resource limit is still enforced for the | |
626 | common privileged daemon workflow\(emnamely, | |
627 | .BR fork (2) | |
628 | + | |
629 | .BR set*uid () | |
630 | + | |
631 | .BR execve (). | |
632 | ||
633 | If the resource limit was not still exceeded at the time of the | |
634 | .BR execve () | |
635 | call | |
636 | (because other processes belonging to this real UID terminated between the | |
84ca1d33 | 637 | .BR set*uid () |
ebd381ba MK |
638 | call and the |
639 | .BR execve () | |
640 | call), then the | |
641 | .BR execve () | |
642 | call succeeds and the kernel clears the | |
643 | .BR PF_NPROC_EXCEEDED | |
644 | process flag. | |
645 | The flag is also cleared if a subsequent call to | |
646 | .BR fork (2) | |
647 | by this process succeeds. | |
8c87824d | 648 | .SS Historical |
b4112efb | 649 | With UNIX\ V6, the argument list of an |
1e321034 MK |
650 | .BR exec () |
651 | call was ended by 0, | |
fea681da MK |
652 | while the argument list of |
653 | .I main | |
677f4766 MK |
654 | was ended by \-1. |
655 | Thus, this argument list was not directly usable in a further | |
c13182ef | 656 | .BR exec () |
1e321034 | 657 | call. |
b4112efb | 658 | Since UNIX\ V7, both are NULL. |
800a8a42 MK |
659 | .\" |
660 | .\" .SH BUGS | |
661 | .\" Some Linux versions have failed to check permissions on ELF | |
662 | .\" interpreters. This is a security hole, because it allows users to | |
663 | .\" open any file, such as a rewinding tape device, for reading. Some | |
664 | .\" Linux versions have also had other security holes in | |
665 | .\" .BR execve () | |
666 | .\" that could be exploited for denial of service by a suitably crafted | |
667 | .\" ELF binary. There are no known problems with 2.0.34 or 2.2.15. | |
e6b33ad7 | 668 | .SH EXAMPLE |
6c48afff | 669 | The following program is designed to be execed by the second program below. |
5f8ddde3 | 670 | It just echoes its command-line arguments, one per line. |
e6b33ad7 | 671 | |
088a639b | 672 | .in +4n |
e6b33ad7 MK |
673 | .nf |
674 | /* myecho.c */ | |
675 | ||
676 | #include <stdio.h> | |
677 | #include <stdlib.h> | |
678 | ||
679 | int | |
680 | main(int argc, char *argv[]) | |
681 | { | |
682 | int j; | |
683 | ||
684 | for (j = 0; j < argc; j++) | |
685 | printf("argv[%d]: %s\\n", j, argv[j]); | |
686 | ||
687 | exit(EXIT_SUCCESS); | |
688 | } | |
689 | .fi | |
690 | .in | |
691 | ||
692 | This program can be used to exec the program named in its command-line | |
693 | argument: | |
088a639b | 694 | .in +4n |
e6b33ad7 MK |
695 | .nf |
696 | ||
697 | /* execve.c */ | |
698 | ||
699 | #include <stdio.h> | |
700 | #include <stdlib.h> | |
701 | #include <unistd.h> | |
e6b33ad7 MK |
702 | |
703 | int | |
704 | main(int argc, char *argv[]) | |
705 | { | |
706 | char *newargv[] = { NULL, "hello", "world", NULL }; | |
707 | char *newenviron[] = { NULL }; | |
708 | ||
6b34fb3f | 709 | if (argc != 2) { |
5a6194a4 MK |
710 | fprintf(stderr, "Usage: %s <file\-to\-exec>\\n", argv[0]); |
711 | exit(EXIT_FAILURE); | |
6b34fb3f MK |
712 | } |
713 | ||
e6b33ad7 MK |
714 | newargv[0] = argv[1]; |
715 | ||
716 | execve(argv[1], newargv, newenviron); | |
312d8fde | 717 | perror("execve"); /* execve() returns only on error */ |
e6b33ad7 MK |
718 | exit(EXIT_FAILURE); |
719 | } | |
720 | .fi | |
721 | .in | |
722 | ||
723 | We can use the second program to exec the first as follows: | |
724 | ||
088a639b | 725 | .in +4n |
e6b33ad7 | 726 | .nf |
b43a3b30 MK |
727 | .RB "$" " cc myecho.c \-o myecho" |
728 | .RB "$" " cc execve.c \-o execve" | |
729 | .RB "$" " ./execve ./myecho" | |
e6b33ad7 MK |
730 | argv[0]: ./myecho |
731 | argv[1]: hello | |
732 | argv[2]: world | |
733 | .fi | |
734 | .in | |
735 | ||
736 | We can also use these programs to demonstrate the use of a script | |
737 | interpreter. | |
738 | To do this we create a script whose "interpreter" is our | |
739 | .I myecho | |
740 | program: | |
741 | ||
088a639b | 742 | .in +4n |
e6b33ad7 | 743 | .nf |
1a212a01 MK |
744 | .RB "$" " cat > script" |
745 | .B #!./myecho script-arg | |
b43a3b30 | 746 | .B ^D |
1a212a01 | 747 | .RB "$" " chmod +x script" |
e6b33ad7 MK |
748 | .fi |
749 | .in | |
750 | ||
751 | We can then use our program to exec the script: | |
752 | ||
088a639b | 753 | .in +4n |
e6b33ad7 | 754 | .nf |
1a212a01 | 755 | .RB "$" " ./execve ./script" |
e6b33ad7 MK |
756 | argv[0]: ./myecho |
757 | argv[1]: script-arg | |
1a212a01 | 758 | argv[2]: ./script |
e6b33ad7 MK |
759 | argv[3]: hello |
760 | argv[4]: world | |
761 | .fi | |
762 | .in | |
47297adb | 763 | .SH SEE ALSO |
fea681da | 764 | .BR chmod (2), |
a940759f | 765 | .BR execveat (2), |
fea681da | 766 | .BR fork (2), |
6aacaf94 | 767 | .BR ptrace (2), |
fea681da | 768 | .BR execl (3), |
9d7f3355 | 769 | .BR fexecve (3), |
d739f5f8 | 770 | .BR getopt (3), |
53a1443c | 771 | .BR credentials (7), |
f0c34053 | 772 | .BR environ (7), |
ad7cc990 | 773 | .BR path_resolution (7), |
fea681da | 774 | .BR ld.so (8) |