1EXECVE(2)                  Linux Programmer's Manual                 EXECVE(2)
2
3
4

NAME

6       execve - execute program
7

SYNOPSIS

9       #include <unistd.h>
10
11       int execve(const char *filename, char *const argv[],
12                  char *const envp[]);
13

DESCRIPTION

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
19           #! interpreter [optional-arg]
20
21       For details of the latter case, see "Interpreter scripts" below.
22
23       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
30           int main(int argc, char *argv[], char *envp[])
31
32       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
35       If  the current program is being ptraced, a SIGTRAP is sent to it after
36       a successful execve().
37
38       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
46       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
51       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
56       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
62       All process attributes are preserved during  an  execve(),  except  the
63       following:
64
65       *      The  dispositions of any signals that are being caught are reset
66              to being ignored.
67
68       *      Any alternate signal stack is not preserved (sigaltstack(2)).
69
70       *      Memory mappings are not preserved (mmap(2)).
71
72       *      Attached  System  V  shared   memory   segments   are   detached
73              (shmat(2)).
74
75       *      POSIX shared memory regions are unmapped (shm_open(3)).
76
77       *      Open  POSIX  message  queue  descriptors  are  closed  (mq_over‐
78              view(7)).
79
80       *      Any open POSIX named semaphores are closed (sem_overview(7)).
81
82       *      POSIX timers are not preserved (timer_create(2)).
83
84       *      Any open directory streams are closed (opendir(3)).
85
86       *      Memory locks are not preserved (mlock(2), mlockall(2)).
87
88       *      Exit handlers are not preserved (atexit(3), on_exit(3)).
89
90       *      The floating-point environment is  reset  to  the  default  (see
91              fenv(3)).
92
93       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
97       *  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
100       *  The prctl(2) PR_SET_KEEPCAPS flag is cleared.
101
102       *  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
105       *  The termination signal is reset to SIGCHLD (see clone(2)).
106
107       Note the following further points:
108
109       *  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
113       *  The  equivalent  of  setlocale(LC_ALL,  "C")  is executed at program
114          start-up.
115
116       *  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
122       *  Any   outstanding   asynchronous   I/O   operations   are   canceled
123          (aio_read(3), aio_write(3)).
124
125       *  For  the  handling  of  capabilities  during execve(), see capabili‐
126          ties(7).
127
128       *  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
142   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
146           #! interpreter [optional-arg]
147
148       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
153           interpreter [optional-arg] filename arg...
154
155       where arg...  is the series of words pointed to by the argv argument of
156       execve().
157
158       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
162   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
169       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
174       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

RETURN VALUE

191       On success, execve() does not return, on  error  -1  is  returned,  and
192       errno is set appropriately.
193

ERRORS

195       E2BIG  The total number of bytes in the environment (envp) and argument
196              list (argv) is too large.
197
198       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
202       EACCES The file or a script interpreter is not a regular file.
203
204       EACCES Execute permission is denied for the file or  a  script  or  ELF
205              interpreter.
206
207       EACCES The file system is mounted noexec.
208
209       EFAULT filename points outside your accessible address space.
210
211       EINVAL An  ELF  executable  had  more than one PT_INTERP segment (i.e.,
212              tried to name more than one interpreter).
213
214       EIO    An I/O error occurred.
215
216       EISDIR An ELF interpreter was a directory.
217
218       ELIBBAD
219              An ELF interpreter was not in a recognized format.
220
221       ELOOP  Too many symbolic links were encountered in  resolving  filename
222              or the name of a script or ELF interpreter.
223
224       EMFILE The process has the maximum number of files open.
225
226       ENAMETOOLONG
227              filename is too long.
228
229       ENFILE The  system  limit  on  the  total number of open files has been
230              reached.
231
232       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
236       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
241       ENOMEM Insufficient kernel memory was available.
242
243       ENOTDIR
244              A component of the path prefix of filename or a  script  or  ELF
245              interpreter is not a directory.
246
247       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
250       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
253       ETXTBSY
254              Executable was open for writing by one or more processes.
255

CONFORMING TO

257       SVr4,  4.3BSD,  POSIX.1-2001.   POSIX.1-2001  does  not document the #!
258       behavior but is otherwise compatible.
259

NOTES

261       Set-user-ID and set-group-ID processes can not be ptrace(2)d.
262
263       Linux ignores the set-user-ID and set-group-ID bits on scripts.
264
265       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
271       A maximum line length of 127 characters is allowed for the  first  line
272       in a #! executable shell script.
273
274       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
283       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
289       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
296   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

EXAMPLE

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
306           /* myecho.c */
307
308           #include <stdio.h>
309           #include <stdlib.h>
310
311           int
312           main(int argc, char *argv[])
313           {
314               int j;
315
316               for (j = 0; j < argc; j++)
317                   printf("argv[%d]: %s\n", j, argv[j]);
318
319               exit(EXIT_SUCCESS);
320           }
321
322       This  program can be used to exec the program named in its command-line
323       argument:
324
325           /* execve.c */
326
327           #include <stdio.h>
328           #include <stdlib.h>
329           #include <unistd.h>
330           #include <assert.h>
331
332           int
333           main(int argc, char *argv[])
334           {
335               char *newargv[] = { NULL, "hello", "world", NULL };
336               char *newenviron[] = { NULL };
337
338               assert(argc == 2);  /* argv[1] identifies
339                                      program to exec */
340               newargv[0] = argv[1];
341
342               execve(argv[1], newargv, newenviron);
343               perror("execve");   /* execve() only returns on error */
344               exit(EXIT_FAILURE);
345           }
346
347       We can use the second program to exec the first as follows:
348
349           $ 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
356       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
360           $ cat > script.sh
361           #! ./myecho script-arg
362           ^D
363           $ chmod +x script.sh
364
365       We can then use our program to exec the script:
366
367           $ ./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

SEE ALSO

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

COLOPHON

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/.
382
383
384
385Linux                             2009-04-21                         EXECVE(2)
Impressum