1EXECVE(2) Linux Programmer's Manual EXECVE(2)
2
6 execve - execute program
7
9 #include <unistd.h>
10 int execve(const char *filename, char *const argv[],
12 char *const envp[]);
13
15 execve() executes the program pointed to by filename. filename must be
16 either a binary executable, or a script starting with a line of the
17 form:
18 #! interpreter [optional-arg]
20 For details of the latter case, see "Interpreter scripts" below.
22 argv is an array of argument strings passed to the new program. envp
24 is an array of strings, conventionally of the form key=value, which are
25 passed as environment to the new program. Both argv and envp must be
26 terminated by a null pointer. The argument vector and environment can
27 be accessed by the called program's main function, when it is defined
28 as:
29 int main(int argc, char *argv[], char *envp[])
31 execve() does not return on success, and the text, data, bss, and stack
33 of the calling process are overwritten by that of the program loaded.
34 If the current program is being ptraced, a SIGTRAP is sent to it after
36 a successful execve().
37 If the set-user-ID bit is set on the program file pointed to by file‐
39 name, and the underlying file system is not mounted nosuid (the
40 MS_NOSUID flag for mount(2)), and the calling process is not being
41 ptraced, then the effective user ID of the calling process is changed
42 to that of the owner of the program file. Similarly, when the set-
43 group-ID bit of the program file is set the effective group ID of the
44 calling process is set to the group of the program file.
45 The effective user ID of the process is copied to the saved set-user-
47 ID; similarly, the effective group ID is copied to the saved set-group-
48 ID. This copying takes place after any effective ID changes that occur
49 because of the set-user-ID and set-group-ID permission bits.
50 If the executable is an a.out dynamically linked binary executable con‐
52 taining shared-library stubs, the Linux dynamic linker ld.so(8) is
53 called at the start of execution to bring needed shared libraries into
54 memory and link the executable with them.
55 If the executable is a dynamically linked ELF executable, the inter‐
57 preter named in the PT_INTERP segment is used to load the needed shared
58 libraries. This interpreter is typically /lib/ld-linux.so.1 for bina‐
59 ries linked with the Linux libc 5, or /lib/ld-linux.so.2 for binaries
60 linked with the glibc 2.
61 All process attributes are preserved during an execve(), except the
63 following:
64 * The dispositions of any signals that are being caught are reset
66 to being ignored.
67 * Any alternate signal stack is not preserved (sigaltstack(2)).
69 * Memory mappings are not preserved (mmap(2)).
71 * Attached System V shared memory segments are detached
73 (shmat(2)).
74 * POSIX shared memory regions are unmapped (shm_open(3)).
76 * Open POSIX message queue descriptors are closed (mq_over‐
78 view(7)).
79 * Any open POSIX named semaphores are closed (sem_overview(7)).
81 * POSIX timers are not preserved (timer_create(2)).
83 * Any open directory streams are closed (opendir(3)).
85 * Memory locks are not preserved (mlock(2), mlockall(2)).
87 * Exit handlers are not preserved (atexit(3), on_exit(3)).
89 * The floating-point environment is reset to the default (see
91 fenv(3)).
92 The process attributes in the preceding list are all specified in
94 POSIX.1-2001. The following Linux-specific process attributes are also
95 not preserved during an execve():
96 * The prctl(2) PR_SET_DUMPABLE flag is set, unless a set-user-ID or
98 set-group ID program is being executed, in which case it is cleared.
99 * The prctl(2) PR_SET_KEEPCAPS flag is cleared.
101 * The process name, as set by prctl(2) PR_SET_NAME (and displayed by
103 ps -o comm), is reset to the name of the new executable file.
104 * The termination signal is reset to SIGCHLD (see clone(2)).
106 Note the following further points:
108 * All threads other than the calling thread are destroyed during an
110 execve(). Mutexes, condition variables, and other pthreads objects
111 are not preserved.
112 * The equivalent of setlocale(LC_ALL, "C") is executed at program
114 start-up.
115 * POSIX.1-2001 specifies that the dispositions of any signals that are
117 ignored or set to the default are left unchanged. POSIX.1-2001
118 specifies one exception: if SIGCHLD is being ignored, then an imple‐
119 mentation may leave the disposition unchanged or reset it to the
120 default; Linux does the former.
121 * Any outstanding asynchronous I/O operations are canceled
123 (aio_read(3), aio_write(3)).
124 * For the handling of capabilities during execve(), see capabili‐
126 ties(7).
127 * By default, file descriptors remain open across an execve(). File
129 descriptors that are marked close-on-exec are closed; see the
130 description of FD_CLOEXEC in fcntl(2). (If a file descriptor is
131 closed, this will cause the release of all record locks obtained on
132 the underlying file by this process. See fcntl(2) for details.)
133 POSIX.1-2001 says that if file descriptors 0, 1, and 2 would other‐
134 wise be closed after a successful execve(), and the process would
135 gain privilege because the set-user_ID or set-group_ID permission
136 bit was set on the executed file, then the system may open an
137 unspecified file for each of these file descriptors. As a general
138 principle, no portable program, whether privileged or not, can
139 assume that these three file descriptors will remain closed across
140 an execve().
141 Interpreter scripts
143 An interpreter script is a text file that has execute permission
144 enabled and whose first line is of the form:
145 #! interpreter [optional-arg]
147 The interpreter must be a valid pathname for an executable which is not
149 itself a script. If the filename argument of execve() specifies an
150 interpreter script, then interpreter will be invoked with the following
151 arguments:
152 interpreter [optional-arg] filename arg...
154 where arg... is the series of words pointed to by the argv argument of
156 execve().
157 For portable use, optional-arg should either be absent, or be specified
159 as a single word (i.e., it should not contain white space); see NOTES
160 below.
161 Limits on size of arguments and environment
163 Most Unix implementations impose some limit on the total size of the
164 command-line argument (argv) and environment (envp) strings that may be
165 passed to a new program. POSIX.1 allows an implementation to advertise
166 this limit using the ARG_MAX constant (either defined in <limits.h> or
167 available at run time using the call sysconf(_SC_ARG_MAX)).
168 On Linux prior to kernel 2.6.23, the memory used to store the environ‐
170 ment and argument strings was limited to 32 pages (defined by the ker‐
171 nel constant MAX_ARG_PAGES). On architectures with a 4-kB page size,
172 this yields a maximum size of 128 kB.
173 On kernel 2.6.23 and later, most architectures support a size limit
175 derived from the soft RLIMIT_STACK resource limit (see getrlimit(2))
176 that is in force at the time of the execve() call. (Architectures with
177 no memory management unit are excepted: they maintain the limit that
178 was in effect before kernel 2.6.23.) This change allows programs to
179 have a much larger argument and/or environment list. For these archi‐
180 tectures, the total size is limited to 1/4 of the allowed stack size.
181 (Imposing the 1/4-limit ensures that the new program always has some
182 stack space.) Since Linux 2.6.25, the kernel places a floor of 32
183 pages on this size limit, so that, even when RLIMIT_STACK is set very
184 low, applications are guaranteed to have at least as much argument and
185 environment space as was provided by Linux 2.6.23 and earlier. (This
186 guarantee was not provided in Linux 2.6.23 and 2.6.24.) Additionally,
187 the limit per string is 32 pages (the kernel constant MAX_ARG_STRLEN),
188 and the maximum number of strings is 0x7FFFFFFF.
189
191 On success, execve() does not return, on error -1 is returned, and
192 errno is set appropriately.
193
195 E2BIG The total number of bytes in the environment (envp) and argument
196 list (argv) is too large.
197 EACCES Search permission is denied on a component of the path prefix of
199 filename or the name of a script interpreter. (See also
200 path_resolution(7).)
201 EACCES The file or a script interpreter is not a regular file.
203 EACCES Execute permission is denied for the file or a script or ELF
205 interpreter.
206 EACCES The file system is mounted noexec.
208 EFAULT filename points outside your accessible address space.
210 EINVAL An ELF executable had more than one PT_INTERP segment (i.e.,
212 tried to name more than one interpreter).
213 EIO An I/O error occurred.
215 EISDIR An ELF interpreter was a directory.
217 ELIBBAD
219 An ELF interpreter was not in a recognized format.
220 ELOOP Too many symbolic links were encountered in resolving filename
222 or the name of a script or ELF interpreter.
223 EMFILE The process has the maximum number of files open.
225 ENAMETOOLONG
227 filename is too long.
228 ENFILE The system limit on the total number of open files has been
230 reached.
231 ENOENT The file filename or a script or ELF interpreter does not exist,
233 or a shared library needed for file or interpreter cannot be
234 found.
235 ENOEXEC
237 An executable is not in a recognized format, is for the wrong
238 architecture, or has some other format error that means it can‐
239 not be executed.
240 ENOMEM Insufficient kernel memory was available.
242 ENOTDIR
244 A component of the path prefix of filename or a script or ELF
245 interpreter is not a directory.
246 EPERM The file system is mounted nosuid, the user is not the supe‐
248 ruser, and the file has the set-user-ID or set-group-ID bit set.
249 EPERM The process is being traced, the user is not the superuser and
251 the file has the set-user-ID or set-group-ID bit set.
252 ETXTBSY
254 Executable was open for writing by one or more processes.
255
257 SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2001 does not document the #!
258 behavior but is otherwise compatible.
259
261 Set-user-ID and set-group-ID processes can not be ptrace(2)d.
262 Linux ignores the set-user-ID and set-group-ID bits on scripts.
264 The result of mounting a file system nosuid varies across Linux kernel
266 versions: some will refuse execution of set-user-ID and set-group-ID
267 executables when this would give the user powers she did not have
268 already (and return EPERM), some will just ignore the set-user-ID and
269 set-group-ID bits and exec() successfully.
270 A maximum line length of 127 characters is allowed for the first line
272 in a #! executable shell script.
273 The semantics of the optional-arg argument of an interpreter script
275 vary across implementations. On Linux, the entire string following the
276 interpreter name is passed as a single argument to the interpreter, and
277 this string can include white space. However, behavior differs on some
278 other systems. Some systems use the first white space to terminate
279 optional-arg. On some systems, an interpreter script can have multiple
280 arguments, and white spaces in optional-arg are used to delimit the
281 arguments.
282 On Linux, argv can be specified as NULL, which has the same effect as
284 specifying this argument as a pointer to a list containing a single
285 NULL pointer. Do not take advantage of this misfeature! It is non-
286 standard and non-portable: on most other Unix systems doing this will
287 result in an error (EFAULT).
288 POSIX.1-2001 says that values returned by sysconf(3) should be invari‐
290 ant over the lifetime of a process. However, since Linux 2.6.23, if
291 the RLIMIT_STACK resource limit changes, then the value reported by
292 _SC_ARG_MAX will also change, to reflect the fact that the limit on
293 space for holding command-line arguments and environment variables has
294 changed.
295 Historical
297 With Unix V6 the argument list of an exec() call was ended by 0, while
298 the argument list of main was ended by -1. Thus, this argument list
299 was not directly usable in a further exec() call. Since Unix V7 both
300 are NULL.
301
303 The following program is designed to be execed by the second program
304 below. It just echoes its command-line one per line.
305 /* myecho.c */
307 #include <stdio.h>
309 #include <stdlib.h>
310 int
312 main(int argc, char *argv[])
313 {
314 int j;
315 for (j = 0; j < argc; j++)
317 printf("argv[%d]: %s\n", j, argv[j]);
318 exit(EXIT_SUCCESS);
320 }
321 This program can be used to exec the program named in its command-line
323 argument:
324 /* execve.c */
326 #include <stdio.h>
328 #include <stdlib.h>
329 #include <unistd.h>
330 #include <assert.h>
331 int
333 main(int argc, char *argv[])
334 {
335 char *newargv[] = { NULL, "hello", "world", NULL };
336 char *newenviron[] = { NULL };
337 assert(argc == 2); /* argv[1] identifies
339 program to exec */
340 newargv[0] = argv[1];
341 execve(argv[1], newargv, newenviron);
343 perror("execve"); /* execve() only returns on error */
344 exit(EXIT_FAILURE);
345 }
346 We can use the second program to exec the first as follows:
348 $ cc myecho.c -o myecho
350 $ cc execve.c -o execve
351 $ ./execve ./myecho
352 argv[0]: ./myecho
353 argv[1]: hello
354 argv[2]: world
355 We can also use these programs to demonstrate the use of a script
357 interpreter. To do this we create a script whose "interpreter" is our
358 myecho program:
359 $ cat > script.sh
361 #! ./myecho script-arg
362 ^D
363 $ chmod +x script.sh
364 We can then use our program to exec the script:
366 $ ./execve ./script.sh
368 argv[0]: ./myecho
369 argv[1]: script-arg
370 argv[2]: ./script.sh
371 argv[3]: hello
372 argv[4]: world
373
375 chmod(2), fork(2), ptrace(2), execl(3), fexecve(3), getopt(3), creden‐
376 tials(7), environ(7), path_resolution(7), ld.so(8)
377
379 This page is part of release 3.22 of the Linux man-pages project. A
380 description of the project, and information about reporting bugs, can
381 be found at http://www.kernel.org/doc/man-pages/.
382Linux 2009-04-21 EXECVE(2)