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 *pathname, char *const argv[],
12                  char *const envp[]);
13

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

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

NOTES

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

EXAMPLE

417       The  following  program  is designed to be execed by the second program
418       below.  It just echoes its command-line arguments, one per line.
419
420           /* myecho.c */
421
422           #include <stdio.h>
423           #include <stdlib.h>
424
425           int
426           main(int argc, char *argv[])
427           {
428               int j;
429
430               for (j = 0; j < argc; j++)
431                   printf("argv[%d]: %s\n", j, argv[j]);
432
433               exit(EXIT_SUCCESS);
434           }
435
436       This program can be used to exec the program named in its  command-line
437       argument:
438
439           /* execve.c */
440
441           #include <stdio.h>
442           #include <stdlib.h>
443           #include <unistd.h>
444
445           int
446           main(int argc, char *argv[])
447           {
448               char *newargv[] = { NULL, "hello", "world", NULL };
449               char *newenviron[] = { NULL };
450
451               if (argc != 2) {
452                   fprintf(stderr, "Usage: %s <file-to-exec>\n", argv[0]);
453                   exit(EXIT_FAILURE);
454               }
455
456               newargv[0] = argv[1];
457
458               execve(argv[1], newargv, newenviron);
459               perror("execve");   /* execve() returns only on error */
460               exit(EXIT_FAILURE);
461           }
462
463       We can use the second program to exec the first as follows:
464
465           $ cc myecho.c -o myecho
466           $ cc execve.c -o execve
467           $ ./execve ./myecho
468           argv[0]: ./myecho
469           argv[1]: hello
470           argv[2]: world
471
472       We  can  also  use  these  programs  to demonstrate the use of a script
473       interpreter.  To do this we create a script whose "interpreter" is  our
474       myecho program:
475
476           $ cat > script
477           #!./myecho script-arg
478           ^D
479           $ chmod +x script
480
481       We can then use our program to exec the script:
482
483           $ ./execve ./script
484           argv[0]: ./myecho
485           argv[1]: script-arg
486           argv[2]: ./script
487           argv[3]: hello
488           argv[4]: world
489

SEE ALSO

491       chmod(2), execveat(2), fork(2), get_robust_list(2), ptrace(2), exec(3),
492       fexecve(3), getopt(3), system(3), credentials(7), environ(7), path_res‐
493       olution(7), ld.so(8)
494

COLOPHON

496       This  page  is  part of release 5.04 of the Linux man-pages project.  A
497       description of the project, information about reporting bugs,  and  the
498       latest     version     of     this    page,    can    be    found    at
499       https://www.kernel.org/doc/man-pages/.
500
501
502
503Linux                             2019-10-10                         EXECVE(2)
Impressum