1execve(2)                     System Calls Manual                    execve(2)
2
3
4

NAME

6       execve - execute program
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int execve(const char *pathname, char *const _Nullable argv[],
15                  char *const _Nullable envp[]);
16

DESCRIPTION

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

RETURN VALUE

252       On  success, execve() does not return, on error -1 is returned, and er‐
253       rno is set to indicate the error.
254

ERRORS

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

VERSIONS

333       POSIX does not document the #! behavior, but it exists (with some vari‐
334       ations) on other UNIX systems.
335
336       On  Linux, argv and envp can be specified as NULL.  In both cases, this
337       has the same effect as specifying the argument as a pointer to  a  list
338       containing  a  single null pointer.  Do not take advantage of this non‐
339       standard and nonportable misfeature!  On many other UNIX systems, spec‐
340       ifying  argv as NULL will result in an error (EFAULT).  Some other UNIX
341       systems treat the envp==NULL case the same as Linux.
342
343       POSIX.1 says that values returned by  sysconf(3)  should  be  invariant
344       over  the  lifetime  of a process.  However, since Linux 2.6.23, if the
345       RLIMIT_STACK  resource  limit  changes,  then  the  value  reported  by
346       _SC_ARG_MAX  will  also  change,  to reflect the fact that the limit on
347       space for holding command-line arguments and environment variables  has
348       changed.
349
350   Interpreter scripts
351       The  kernel  imposes a maximum length on the text that follows the "#!"
352       characters at the start of a script; characters beyond  the  limit  are
353       ignored.   Before  Linux 5.1, the limit is 127 characters.  Since Linux
354       5.1, the limit is 255 characters.
355
356       The semantics of the optional-arg argument  of  an  interpreter  script
357       vary across implementations.  On Linux, the entire string following the
358       interpreter name is passed as a single argument to the interpreter, and
359       this string can include white space.  However, behavior differs on some
360       other systems.  Some systems use the first white space to terminate op‐
361       tional-arg.   On  some systems, an interpreter script can have multiple
362       arguments, and white spaces in optional-arg are used to delimit the ar‐
363       guments.
364
365       Linux (like most other modern UNIX systems) ignores the set-user-ID and
366       set-group-ID bits on scripts.
367

STANDARDS

369       POSIX.1-2008.
370

HISTORY

372       POSIX.1-2001, SVr4, 4.3BSD.
373
374       With UNIX V6, the argument list of an exec() call was ended by 0, while
375       the  argument  list  of main was ended by -1.  Thus, this argument list
376       was not directly usable in a further exec() call.  Since UNIX V7,  both
377       are NULL.
378

NOTES

380       One  sometimes  sees  execve()  (and the related functions described in
381       exec(3)) described as "executing a new process" (or similar).  This  is
382       a  highly  misleading  description:  there  is no new process; many at‐
383       tributes of the calling process remain unchanged  (in  particular,  its
384       PID).   All  that execve() does is arrange for an existing process (the
385       calling process) to execute a new program.
386
387       Set-user-ID and set-group-ID processes can not be ptrace(2)d.
388
389       The result of mounting a filesystem nosuid varies across  Linux  kernel
390       versions:  some  will  refuse execution of set-user-ID and set-group-ID
391       executables when this would give the user powers they did not have  al‐
392       ready  (and  return  EPERM),  some will just ignore the set-user-ID and
393       set-group-ID bits and exec() successfully.
394
395       In most cases where execve() fails, control returns to the original ex‐
396       ecutable  image,  and the caller of execve() can then handle the error.
397       However, in (rare) cases (typically  caused  by  resource  exhaustion),
398       failure  may occur past the point of no return: the original executable
399       image has been torn down, but the new image  could  not  be  completely
400       built.   In  such  cases,  the  kernel kills the process with a SIGSEGV
401       (SIGKILL until Linux 3.17) signal.
402
403   execve() and EAGAIN
404       A more detailed explanation of the EAGAIN error that can  occur  (since
405       Linux 3.1) when calling execve() is as follows.
406
407       The  EAGAIN  error  can  occur  when a preceding call to setuid(2), se‐
408       treuid(2), or setresuid(2) caused the real user ID of  the  process  to
409       change,  and  that change caused the process to exceed its RLIMIT_NPROC
410       resource limit (i.e., the number of processes belonging to the new real
411       UID  exceeds  the resource limit).  From Linux 2.6.0 to Linux 3.0, this
412       caused the set*uid() call to fail.  (Before  Linux  2.6,  the  resource
413       limit was not imposed on processes that changed their user IDs.)
414
415       Since  Linux  3.1,  the  scenario  just  described no longer causes the
416       set*uid() call to fail, because it too  often  led  to  security  holes
417       where  buggy  applications  didn't  check the return status and assumed
418       that—if the caller had root privileges—the call would  always  succeed.
419       Instead,  the set*uid() calls now successfully change the real UID, but
420       the kernel sets an internal flag, named PF_NPROC_EXCEEDED, to note that
421       the RLIMIT_NPROC resource limit has been exceeded.  If the PF_NPROC_EX‐
422       CEEDED flag is set and the resource limit is still exceeded at the time
423       of  a  subsequent execve() call, that call fails with the error EAGAIN.
424       This kernel logic ensures that the RLIMIT_NPROC resource limit is still
425       enforced  for  the  common privileged daemon workflow—namely, fork(2) +
426       set*uid() + execve().
427
428       If the resource limit was not still exceeded at the  time  of  the  ex‐
429       ecve()  call (because other processes belonging to this real UID termi‐
430       nated between the set*uid() call and the execve() call), then  the  ex‐
431       ecve()  call  succeeds  and  the  kernel  clears  the PF_NPROC_EXCEEDED
432       process flag.  The flag is also cleared if a subsequent call to fork(2)
433       by this process succeeds.
434

EXAMPLES

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

SEE ALSO

508       chmod(2), execveat(2), fork(2), get_robust_list(2), ptrace(2), exec(3),
509       fexecve(3), getauxval(3), getopt(3), system(3),  capabilities(7),  cre‐
510       dentials(7), environ(7), path_resolution(7), ld.so(8)
511
512
513
514Linux man-pages 6.05              2023-05-03                         execve(2)
Impressum