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


6       execve - execute program


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


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:
19           #! interpreter [optional-arg]
21       For details of the latter case, see "Interpreter scripts" below.
23       argv  is  an  array  of argument strings passed to the new program.  By
24       convention, the first of these strings (i.e., argv[0])  should  contain
25       the filename associated with the file being executed.  envp is an array
26       of strings, conventionally of the form key=value, which are  passed  as
27       environment  to  the  new  program.  The argv and envp arrays must each
28       include a null pointer at the end of the array.
30       The argument vector and environment can be accessed by the called  pro‐
31       gram's main function, when it is defined as:
33           int main(int argc, char *argv[], char *envp[])
35       Note, however, that the use of a third argument to the main function is
36       not specified in POSIX.1; according to POSIX.1, the environment  should
37       be accessed via the external variable environ(7).
39       execve()  does  not  return on success, and the text, initialized data,
40       uninitialized data (bss), and stack of the calling  process  are  over‐
41       written according to the contents of the newly loaded program.
43       If the current program is being ptraced, a SIGTRAP signal is sent to it
44       after a successful execve().
46       If the set-user-ID bit is set on the program file pointed to  by  file‐
47       name,  then  the effective user ID of the calling process is changed to
48       that of the owner of the program file.  Similarly, when the  set-group-
49       ID bit of the program file is set the effective group ID of the calling
50       process is set to the group of the program file.
52       The aforementioned transformations of the effective IDs  are  not  per‐
53       formed (i.e., the set-user-ID and set-group-ID bits are ignored) if any
54       of the following is true:
56       *  the no_new_privs attribute  is  set  for  the  calling  thread  (see
57          prctl(2));
59       *  the  underlying filesystem is mounted nosuid (the MS_NOSUID flag for
60          mount(2)); or
62       *  the calling process is being ptraced.
64       The capabilities of the program file  (see  capabilities(7))  are  also
65       ignored if any of the above are true.
67       The  effective  user ID of the process is copied to the saved set-user-
68       ID; similarly, the effective group ID is copied to the saved set-group-
69       ID.  This copying takes place after any effective ID changes that occur
70       because of the set-user-ID and set-group-ID mode bits.
72       The process's real UID and real GID, as well  its  supplementary  group
73       IDs, are unchanged by a call to execve().
75       If the executable is an a.out dynamically linked binary executable con‐
76       taining shared-library stubs, the  Linux  dynamic  linker  ld.so(8)  is
77       called  at  the  start of execution to bring needed shared objects into
78       memory and link the executable with them.
80       If the executable is a dynamically linked ELF  executable,  the  inter‐
81       preter named in the PT_INTERP segment is used to load the needed shared
82       objects.  This interpreter is typically /lib/ld-linux.so.2 for binaries
83       linked with glibc (see ld-linux.so(8)).
85       All  process  attributes  are  preserved during an execve(), except the
86       following:
88       *  The dispositions of any signals that are being caught are  reset  to
89          the default (signal(7)).
91       *  Any alternate signal stack is not preserved (sigaltstack(2)).
93       *  Memory mappings are not preserved (mmap(2)).
95       *  Attached System V shared memory segments are detached (shmat(2)).
97       *  POSIX shared memory regions are unmapped (shm_open(3)).
99       *  Open POSIX message queue descriptors are closed (mq_overview(7)).
101       *  Any open POSIX named semaphores are closed (sem_overview(7)).
103       *  POSIX timers are not preserved (timer_create(2)).
105       *  Any open directory streams are closed (opendir(3)).
107       *  Memory locks are not preserved (mlock(2), mlockall(2)).
109       *  Exit handlers are not preserved (atexit(3), on_exit(3)).
111       *  The   floating-point  environment  is  reset  to  the  default  (see
112          fenv(3)).
114       The process attributes in the  preceding  list  are  all  specified  in
115       POSIX.1.   The following Linux-specific process attributes are also not
116       preserved during an execve():
118       *  The prctl(2) PR_SET_DUMPABLE flag is set, unless  a  set-user-ID  or
119          set-group ID program is being executed, in which case it is cleared.
121       *  The prctl(2) PR_SET_KEEPCAPS flag is cleared.
123       *  (Since  Linux 2.4.36 / 2.6.23) If a set-user-ID or set-group-ID pro‐
124          gram is being executed, then the parent death signal set by prctl(2)
125          PR_SET_PDEATHSIG flag is cleared.
127       *  The  process  name, as set by prctl(2) PR_SET_NAME (and displayed by
128          ps -o comm), is reset to the name of the new executable file.
130       *  The SECBIT_KEEP_CAPS securebits  flag  is  cleared.   See  capabili‐
131          ties(7).
133       *  The termination signal is reset to SIGCHLD (see clone(2)).
135       *  The  file  descriptor  table  is unshared, undoing the effect of the
136          CLONE_FILES flag of clone(2).
138       Note the following further points:
140       *  All threads other than the calling thread are  destroyed  during  an
141          execve().   Mutexes, condition variables, and other pthreads objects
142          are not preserved.
144       *  The equivalent of setlocale(LC_ALL,  "C")  is  executed  at  program
145          start-up.
147       *  POSIX.1  specifies  that  the  dispositions  of any signals that are
148          ignored or set to the default are left unchanged.  POSIX.1 specifies
149          one  exception:  if SIGCHLD is being ignored, then an implementation
150          may leave the disposition unchanged or  reset  it  to  the  default;
151          Linux does the former.
153       *  Any   outstanding   asynchronous   I/O   operations   are   canceled
154          (aio_read(3), aio_write(3)).
156       *  For the handling of  capabilities  during  execve(),  see  capabili‐
157          ties(7).
159       *  By  default,  file descriptors remain open across an execve().  File
160          descriptors that  are  marked  close-on-exec  are  closed;  see  the
161          description  of  FD_CLOEXEC  in  fcntl(2).  (If a file descriptor is
162          closed, this will cause the release of all record locks obtained  on
163          the  underlying  file  by  this process.  See fcntl(2) for details.)
164          POSIX.1 says that if file descriptors 0, 1, and 2 would otherwise be
165          closed after a successful execve(), and the process would gain priv‐
166          ilege because the set-user-ID or set-group_ID mode bit  was  set  on
167          the  executed file, then the system may open an unspecified file for
168          each of these file descriptors.  As a general principle, no portable
169          program, whether privileged or not, can assume that these three file
170          descriptors will remain closed across an execve().
172   Interpreter scripts
173       An interpreter script is  a  text  file  that  has  execute  permission
174       enabled and whose first line is of the form:
176           #! interpreter [optional-arg]
178       The  interpreter  must  be a valid pathname for an executable file.  If
179       the filename argument of execve() specifies an interpreter script, then
180       interpreter will be invoked with the following arguments:
182           interpreter [optional-arg] filename arg...
184       where arg...  is the series of words pointed to by the argv argument of
185       execve(), starting at argv[1].
187       For portable use, optional-arg should either be absent, or be specified
188       as  a  single word (i.e., it should not contain white space); see NOTES
189       below.
191       Since Linux 2.6.28, the kernel permits the interpreter of a  script  to
192       itself  be  a  script.   This permission is recursive, up to a limit of
193       four recursions, so that the interpreter  may  be  a  script  which  is
194       interpreted by a script, and so on.
196   Limits on size of arguments and environment
197       Most  UNIX  implementations  impose some limit on the total size of the
198       command-line argument (argv) and environment (envp) strings that may be
199       passed to a new program.  POSIX.1 allows an implementation to advertise
200       this limit using the ARG_MAX constant (either defined in <limits.h>  or
201       available at run time using the call sysconf(_SC_ARG_MAX)).
203       On  Linux prior to kernel 2.6.23, the memory used to store the environ‐
204       ment and argument strings was limited to 32 pages (defined by the  ker‐
205       nel  constant  MAX_ARG_PAGES).  On architectures with a 4-kB page size,
206       this yields a maximum size of 128 kB.
208       On kernel 2.6.23 and later, most architectures  support  a  size  limit
209       derived  from  the  soft RLIMIT_STACK resource limit (see getrlimit(2))
210       that is in force at the time of the execve() call.  (Architectures with
211       no  memory  management  unit are excepted: they maintain the limit that
212       was in effect before kernel 2.6.23.)  This change  allows  programs  to
213       have  a much larger argument and/or environment list.  For these archi‐
214       tectures, the total size is limited to 1/4 of the allowed  stack  size.
215       (Imposing  the  1/4-limit  ensures that the new program always has some
216       stack space.)  Since Linux 2.6.25, the kernel  places  a  floor  of  32
217       pages  on  this size limit, so that, even when RLIMIT_STACK is set very
218       low, applications are guaranteed to have at least as much argument  and
219       environment  space  as was provided by Linux 2.6.23 and earlier.  (This
220       guarantee was not provided in Linux 2.6.23 and 2.6.24.)   Additionally,
221       the  limit per string is 32 pages (the kernel constant MAX_ARG_STRLEN),
222       and the maximum number of strings is 0x7FFFFFFF.


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


229       E2BIG  The total number of bytes in the environment (envp) and argument
230              list (argv) is too large.
232       EACCES Search permission is denied on a component of the path prefix of
233              filename  or  the  name  of  a  script  interpreter.   (See also
234              path_resolution(7).)
236       EACCES The file or a script interpreter is not a regular file.
238       EACCES Execute permission is denied for the file or  a  script  or  ELF
239              interpreter.
241       EACCES The filesystem is mounted noexec.
243       EAGAIN (since Linux 3.1)
244              Having  changed  its  real UID using one of the set*uid() calls,
245              the caller was—and is now still—above its RLIMIT_NPROC  resource
246              limit  (see  setrlimit(2)).   For a more detailed explanation of
247              this error, see NOTES.
249       EFAULT filename or one of the pointers in  the  vectors  argv  or  envp
250              points outside your accessible address space.
252       EINVAL An  ELF  executable  had  more than one PT_INTERP segment (i.e.,
253              tried to name more than one interpreter).
255       EIO    An I/O error occurred.
257       EISDIR An ELF interpreter was a directory.
259       ELIBBAD
260              An ELF interpreter was not in a recognized format.
262       ELOOP  Too many symbolic links were encountered in  resolving  filename
263              or the name of a script or ELF interpreter.
265       ELOOP  The  maximum recursion limit was reached during recursive script
266              interpretation (see "Interpreter scripts", above).  Before Linux
267              3.8, the error produced for this case was ENOEXEC.
269       EMFILE The per-process limit on the number of open file descriptors has
270              been reached.
273              filename is too long.
275       ENFILE The system-wide limit on the total number of open files has been
276              reached.
278       ENOENT The file filename or a script or ELF interpreter does not exist,
279              or a shared library needed for the file or interpreter cannot be
280              found.
282       ENOEXEC
283              An  executable  is  not in a recognized format, is for the wrong
284              architecture, or has some other format error that means it  can‐
285              not be executed.
287       ENOMEM Insufficient kernel memory was available.
289       ENOTDIR
290              A  component  of  the path prefix of filename or a script or ELF
291              interpreter is not a directory.
293       EPERM  The filesystem is mounted nosuid, the user is not the superuser,
294              and the file has the set-user-ID or set-group-ID bit set.
296       EPERM  The  process  is being traced, the user is not the superuser and
297              the file has the set-user-ID or set-group-ID bit set.
299       EPERM  A "capability-dumb" applications would not obtain the  full  set
300              of  permitted  capabilities granted by the executable file.  See
301              capabilities(7).
303       ETXTBSY
304              The specified executable was open for writing  by  one  or  more
305              processes.


308       POSIX.1-2001,  POSIX.1-2008, SVr4, 4.3BSD.  POSIX does not document the
309       #! behavior, but it exists (with some variations) on  other  UNIX  sys‐
310       tems.


313       Set-user-ID and set-group-ID processes can not be ptrace(2)d.
315       The  result  of mounting a filesystem nosuid varies across Linux kernel
316       versions: some will refuse execution of  set-user-ID  and  set-group-ID
317       executables  when  this  would  give  the  user powers she did not have
318       already (and return EPERM), some will just ignore the  set-user-ID  and
319       set-group-ID bits and exec() successfully.
321       On  Linux, argv and envp can be specified as NULL.  In both cases, this
322       has the same effect as specifying the argument as a pointer to  a  list
323       containing  a  single null pointer.  Do not take advantage of this non‐
324       standard and nonportable misfeature!  On many other UNIX systems, spec‐
325       ifying  argv as NULL will result in an error (EFAULT).  Some other UNIX
326       systems treat the envp==NULL case the same as Linux.
328       POSIX.1 says that values returned by  sysconf(3)  should  be  invariant
329       over  the  lifetime  of a process.  However, since Linux 2.6.23, if the
330       RLIMIT_STACK  resource  limit  changes,  then  the  value  reported  by
331       _SC_ARG_MAX  will  also  change,  to reflect the fact that the limit on
332       space for holding command-line arguments and environment variables  has
333       changed.
335       In  most  cases  where  execve() fails, control returns to the original
336       executable image, and the caller of execve() can then handle the error.
337       However,  in  (rare)  cases  (typically caused by resource exhaustion),
338       failure may occur past the point of no return: the original  executable
339       image  has  been  torn  down, but the new image could not be completely
340       built.  In such cases, the kernel kills the process with a SIGKILL sig‐
341       nal.
343   Interpreter scripts
344       A  maximum  line length of 127 characters is allowed for the first line
345       in an interpreter script.
347       The semantics of the optional-arg argument  of  an  interpreter  script
348       vary across implementations.  On Linux, the entire string following the
349       interpreter name is passed as a single argument to the interpreter, and
350       this string can include white space.  However, behavior differs on some
351       other systems.  Some systems use the first  white  space  to  terminate
352       optional-arg.  On some systems, an interpreter script can have multiple
353       arguments, and white spaces in optional-arg are  used  to  delimit  the
354       arguments.
356       Linux ignores the set-user-ID and set-group-ID bits on scripts.
358   execve() and EAGAIN
359       A  more  detailed explanation of the EAGAIN error that can occur (since
360       Linux 3.1) when calling execve() is as follows.
362       The EAGAIN  error  can  occur  when  a  preceding  call  to  setuid(2),
363       setreuid(2),  or setresuid(2) caused the real user ID of the process to
364       change, and that change caused the process to exceed  its  RLIMIT_NPROC
365       resource limit (i.e., the number of processes belonging to the new real
366       UID exceeds the resource limit).  From Linux 2.6.0 to 3.0, this  caused
367       the  set*uid() call to fail.  (Prior to 2.6, the resource limit was not
368       imposed on processes that changed their user IDs.)
370       Since Linux 3.1, the scenario  just  described  no  longer  causes  the
371       set*uid()  call  to  fail,  because  it too often led to security holes
372       where buggy applications didn't check the  return  status  and  assumed
373       that—if  the  caller had root privileges—the call would always succeed.
374       Instead, the set*uid() calls now successfully change the real UID,  but
375       the kernel sets an internal flag, named PF_NPROC_EXCEEDED, to note that
376       the  RLIMIT_NPROC  resource  limit   has   been   exceeded.    If   the
377       PF_NPROC_EXCEEDED  flag is set and the resource limit is still exceeded
378       at the time of a subsequent execve() call, that  call  fails  with  the
379       error EAGAIN.  This kernel logic ensures that the RLIMIT_NPROC resource
380       limit is still enforced for  the  common  privileged  daemon  workflow—
381       namely, fork(2) + set*uid() + execve().
383       If  the  resource  limit  was  not  still  exceeded  at the time of the
384       execve() call (because other processes belonging to this real UID  ter‐
385       minated  between  the  set*uid()  call and the execve() call), then the
386       execve() call succeeds and  the  kernel  clears  the  PF_NPROC_EXCEEDED
387       process flag.  The flag is also cleared if a subsequent call to fork(2)
388       by this process succeeds.
390   Historical
391       With UNIX V6, the argument list of an exec() call was ended by 0, while
392       the  argument  list  of main was ended by -1.  Thus, this argument list
393       was not directly usable in a further exec() call.  Since UNIX V7,  both
394       are NULL.


397       The  following  program  is designed to be execed by the second program
398       below.  It just echoes its command-line arguments, one per line.
400           /* myecho.c */
402           #include <stdio.h>
403           #include <stdlib.h>
405           int
406           main(int argc, char *argv[])
407           {
408               int j;
410               for (j = 0; j < argc; j++)
411                   printf("argv[%d]: %s\n", j, argv[j]);
413               exit(EXIT_SUCCESS);
414           }
416       This program can be used to exec the program named in its  command-line
417       argument:
419           /* execve.c */
421           #include <stdio.h>
422           #include <stdlib.h>
423           #include <unistd.h>
425           int
426           main(int argc, char *argv[])
427           {
428               char *newargv[] = { NULL, "hello", "world", NULL };
429               char *newenviron[] = { NULL };
431               if (argc != 2) {
432                   fprintf(stderr, "Usage: %s <file-to-exec>\n", argv[0]);
433                   exit(EXIT_FAILURE);
434               }
436               newargv[0] = argv[1];
438               execve(argv[1], newargv, newenviron);
439               perror("execve");   /* execve() returns only on error */
440               exit(EXIT_FAILURE);
441           }
443       We can use the second program to exec the first as follows:
445           $ cc myecho.c -o myecho
446           $ cc execve.c -o execve
447           $ ./execve ./myecho
448           argv[0]: ./myecho
449           argv[1]: hello
450           argv[2]: world
452       We  can  also  use  these  programs  to demonstrate the use of a script
453       interpreter.  To do this we create a script whose "interpreter" is  our
454       myecho program:
456           $ cat > script
457           #!./myecho script-arg
458           ^D
459           $ chmod +x script
461       We can then use our program to exec the script:
463           $ ./execve ./script
464           argv[0]: ./myecho
465           argv[1]: script-arg
466           argv[2]: ./script
467           argv[3]: hello
468           argv[4]: world


471       chmod(2),    execveat(2),   fork(2),   get_robust_list(2),   ptrace(2),
472       execl(3), fexecve(3), getopt(3), system(3), credentials(7), environ(7),
473       path_resolution(7), ld.so(8)


476       This  page  is  part of release 4.15 of the Linux man-pages project.  A
477       description of the project, information about reporting bugs,  and  the
478       latest     version     of     this    page,    can    be    found    at
479       https://www.kernel.org/doc/man-pages/.
483Linux                             2017-09-15                         EXECVE(2)