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 "#! interpreter [arg]". In the latter case, the interpreter must
18 be a valid pathname for an executable which is not itself a script,
19 which will be invoked as interpreter [arg] filename.
20 argv is an array of argument strings passed to the new program. envp
22 is an array of strings, conventionally of the form key=value, which are
23 passed as environment to the new program. Both argv and envp must be
24 terminated by a null pointer. The argument vector and environment can
25 be accessed by the called program's main function, when it is defined
26 as int main(int argc, char *argv[], char *envp[]).
27 execve() does not return on success, and the text, data, bss, and stack
29 of the calling process are overwritten by that of the program loaded.
30 If the current program is being ptraced, a SIGTRAP is sent to it after
32 a successful execve().
33 If the set-user-ID bit is set on the program file pointed to by file‐
35 name, and the calling process is not being ptraced, then the effective
36 user ID of the calling process is changed to that of the owner of the
37 program file. Similarly, when the set-group-ID bit of the program file
38 is set the effective group ID of the calling process is set to the
39 group of the program file.
40 The effective user ID of the process is copied to the saved set-user-
42 ID; similarly, the effective group ID is copied to the saved set-group-
43 ID. This copying takes place after any effective ID changes that occur
44 because of the set-user-ID and set-group-ID permission bits.
45 If the executable is an a.out dynamically-linked binary executable con‐
47 taining shared-library stubs, the Linux dynamic linker ld.so(8) is
48 called at the start of execution to bring needed shared libraries into
49 memory and link the executable with them.
50 If the executable is a dynamically-linked ELF executable, the inter‐
52 preter named in the PT_INTERP segment is used to load the needed shared
53 libraries. This interpreter is typically /lib/ld-linux.so.1 for bina‐
54 ries linked with the Linux libc version 5, or /lib/ld-linux.so.2 for
55 binaries linked with the GNU libc version 2.
56 All process attributes are preserved during an execve(), except the
58 following:
59 * File descriptors that are marked close-on-exec are closed (see the
61 description of FD_CLOEXEC in fcntl(2)).
62 * The set of pending signals is cleared (sigpending(2)).
64 * The dispositions of any signals that are being caught are reset to
66 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 (shmat(2)).
73 * POSIX shared memory regions are unmapped (shm_open(3)).
75 * Open POSIX message queue descriptors are closed (mq_overview(7)).
77 * Any open POSIX named semaphores are closed (sem_overview(7)).
79 * POSIX timers are not preserved (timer_create(3)).
81 * Any open directory streams are closed (opendir(3)).
83 * Memory locks are not preserved (mlock(2), mlockall(2)).
85 * Exit handlers are not preserved (atexit(3), on_exit(3)).
87 The process attributes in the preceding list are all specified in
89 POSIX.1-2001. The following Linux-specific process attributes are also
90 not preserved during an execve():
91 * The prctl(2) PR_SET_DUMPABLE flag is set, unless a set-user-ID or
93 set-group ID program is being executed, in which case it is
94 cleared.
95 * The prctl(2) PR_SET_KEEPCAPS flag is cleared.
97 * The process name, as set by prctl(2) PR_SET_NAME (and displayed by
99 ps -o comm), is reset to the name of the new executable file.
100 * The termination signal is reset to SIGCHLD (see clone(2)).
102 Note the following further points:
104 * All threads other than calling thread are destroyed during an
106 execve(). Mutexes, condition variables, and other pthreads objects
107 are not preserved.
108 * The equivalent of setlocale(LC_ALL, "C") is executed at program
110 start-up.
111 * POSIX.1-2001 specifies that the dispositions of any signals that
113 are ignored or set to the default are left unchanged. POSIX.1-2001
114 specifies one exception: if SIGCHLD is being ignored, then an
115 implementation may leave the disposition unchanged or reset it to
116 the default; Linux does the former.
117 * Any outstanding asynchronous I/O operations are cancelled
119 (aio_read(3), aio_write(3)).
120 * For the handling of capabilities during execve(2), see capabili‐
122 ties(7).
123
125 On success, execve() does not return, on error -1 is returned, and
126 errno is set appropriately.
127
129 E2BIG The total number of bytes in the environment (envp) and argument
130 list (argv) is too large.
131 EACCES Search permission is denied on a component of the path prefix of
133 filename or the name of a script interpreter. (See also
134 path_resolution(2).)
135 EACCES The file or a script interpreter is not a regular file.
137 EACCES Execute permission is denied for the file or a script or ELF
139 interpreter.
140 EACCES The file system is mounted noexec.
142 EFAULT filename points outside your accessible address space.
144 EINVAL An ELF executable had more than one PT_INTERP segment (i.e.,
146 tried to name more than one interpreter).
147 EIO An I/O error occurred.
149 EISDIR An ELF interpreter was a directory.
151 ELIBBAD
153 An ELF interpreter was not in a recognised format.
154 ELOOP Too many symbolic links were encountered in resolving filename
156 or the name of a script or ELF interpreter.
157 EMFILE The process has the maximum number of files open.
159 ENAMETOOLONG
161 filename is too long.
162 ENFILE The system limit on the total number of open files has been
164 reached.
165 ENOENT The file filename or a script or ELF interpreter does not exist,
167 or a shared library needed for file or interpreter cannot be
168 found.
169 ENOEXEC
171 An executable is not in a recognised format, is for the wrong
172 architecture, or has some other format error that means it can‐
173 not be executed.
174 ENOMEM Insufficient kernel memory was available.
176 ENOTDIR
178 A component of the path prefix of filename or a script or ELF
179 interpreter is not a directory.
180 EPERM The file system is mounted nosuid, the user is not the supe‐
182 ruser, and the file has the set-user-ID or set-group-ID bit set.
183 EPERM The process is being traced, the user is not the superuser and
185 the file has the set-user-ID or set-group-ID bit set.
186 ETXTBSY
188 Executable was open for writing by one or more processes.
189
191 SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2001 does not document the #!
192 behavior but is otherwise compatible.
193
195 Set-user-ID and set-group-ID processes can not be ptrace()d.
196 Linux ignores the set-user-ID and set-group-ID bits on scripts.
198 The result of mounting a filesystem nosuid vary between Linux kernel
200 versions: some will refuse execution of set-user-ID and set-group-ID
201 executables when this would give the user powers she did not have
202 already (and return EPERM), some will just ignore the set-user-ID and
203 set-group-ID bits and exec() successfully.
204 A maximum line length of 127 characters is allowed for the first line
206 in a #! executable shell script.
207
210 With Unix V6 the argument list of an exec() call was ended by 0, while
211 the argument list of main was ended by -1. Thus, this argument list was
212 not directly usable in a further exec() call. Since Unix V7 both are
213 NULL.
214
217 chmod(2), fork(2), path_resolution(2), ptrace(2), execl(3), fexecve(3),
218 environ(7), ld.so(8)
219Linux 2.6.17 2006-09-04 EXECVE(2)