1EXEC(3P)                   POSIX Programmer's Manual                  EXEC(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       environ, execl, execle, execlp, execv, execve, execvp, fexecve  —  exe‐
13       cute a file
14

SYNOPSIS

16       #include <unistd.h>
17
18       extern char **environ;
19       int execl(const char *path, const char *arg0, ... /*, (char *)0 */);
20       int execle(const char *path, const char *arg0, ... /*,
21           (char *)0, char *const envp[]*/);
22       int execlp(const char *file, const char *arg0, ... /*, (char *)0 */);
23       int execv(const char *path, char *const argv[]);
24       int execve(const char *path, char *const argv[], char *const envp[]);
25       int execvp(const char *file, char *const argv[]);
26       int fexecve(int fd, char *const argv[], char *const envp[]);
27

DESCRIPTION

29       The  exec  family  of functions shall replace the current process image
30       with a new process image. The new image shall  be  constructed  from  a
31       regular,  executable  file  called  the  new process image file.  There
32       shall be no return from a successful exec, because the calling  process
33       image is overlaid by the new process image.
34
35       The  fexecve()  function  shall  be equivalent to the execve() function
36       except that the file to be executed is determined by the file  descrip‐
37       tor fd instead of a pathname. The file offset of fd is ignored.
38
39       When  a  C-language program is executed as a result of a call to one of
40       the exec family of functions, it shall be entered as a C-language func‐
41       tion call as follows:
42
43
44           int main (int argc, char *argv[]);
45
46       where  argc  is  the  argument  count and argv is an array of character
47       pointers to the arguments themselves.  In addition, the following vari‐
48       able, which must be declared by the user if it is to be used directly:
49
50
51           extern char **environ;
52
53       is  initialized  as  a pointer to an array of character pointers to the
54       environment strings. The argv and environ arrays are each terminated by
55       a  null  pointer.  The  null  pointer terminating the argv array is not
56       counted in argc.
57
58       Applications can change the entire environment in a single operation by
59       assigning the environ variable to point to an array of character point‐
60       ers to the new environment strings. After assigning a new value to env‐
61       iron,  applications  should  not  rely  on  the new environment strings
62       remaining part of the environment, as a  call  to  getenv(),  putenv(),
63       setenv(),  unsetenv(), or any function that is dependent on an environ‐
64       ment variable may, on noticing that environ has changed, copy the envi‐
65       ronment strings to a new array and assign environ to point to it.
66
67       Any  application that directly modifies the pointers to which the envi‐
68       ron variable points has undefined behavior.
69
70       Conforming multi-threaded applications shall not use the environ  vari‐
71       able  to  access  or  modify  any  environment variable while any other
72       thread is concurrently modifying any environment variable.  A  call  to
73       any  function dependent on any environment variable shall be considered
74       a use of the environ variable to access that environment variable.
75
76       The arguments specified by a program with one  of  the  exec  functions
77       shall be passed on to the new process image in the corresponding main()
78       arguments.
79
80       The argument path points to a pathname that identifies the new  process
81       image file.
82
83       The  argument  file is used to construct a pathname that identifies the
84       new process image file. If the file argument contains a <slash> charac‐
85       ter,  the  file  argument  shall be used as the pathname for this file.
86       Otherwise, the path prefix for this file is obtained by a search of the
87       directories passed as the environment variable PATH (see the Base Defi‐
88       nitions volume of POSIX.1‐2017, Chapter 8, Environment Variables).   If
89       this environment variable is not present, the results of the search are
90       implementation-defined.
91
92       There are two distinct ways in which the contents of the process  image
93       file  may  cause the execution to fail, distinguished by the setting of
94       errno to either [ENOEXEC] or [EINVAL] (see the ERRORS section). In  the
95       cases  where  the  other  members of the exec family of functions would
96       fail and set errno to [ENOEXEC], the execlp()  and  execvp()  functions
97       shall execute a command interpreter and the environment of the executed
98       command shall be as if the process invoked the sh utility using execl()
99       as follows:
100
101
102           execl(<shell path>, arg0, file, arg1, ..., (char *)0);
103
104       where  <shell path> is an unspecified pathname for the sh utility, file
105       is the process image file, and for execvp(), where arg0, arg1,  and  so
106       on correspond to the values passed to execvp() in argv[0], argv[1], and
107       so on.
108
109       The arguments represented by arg0,...  are pointers to  null-terminated
110       character  strings.  These  strings  shall constitute the argument list
111       available to the new process image. The list is terminated  by  a  null
112       pointer.  The  argument  arg0 should point to a filename string that is
113       associated with the process being started by one of the exec functions.
114
115       The argument argv is an array of character pointers to  null-terminated
116       strings.  The  application  shall  ensure  that the last member of this
117       array is a null pointer. These strings shall  constitute  the  argument
118       list  available  to  the new process image. The value in argv[0] should
119       point to a filename string that is associated with  the  process  being
120       started by one of the exec functions.
121
122       The  argument envp is an array of character pointers to null-terminated
123       strings. These strings shall constitute the  environment  for  the  new
124       process image.  The envp array is terminated by a null pointer.
125
126       For  those forms not containing an envp pointer (execl(), execv(), exe‐
127       clp(), and execvp()), the environment for the new process  image  shall
128       be taken from the external variable environ in the calling process.
129
130       The  number  of  bytes available for the new process' combined argument
131       and environment  lists  is  {ARG_MAX}.   It  is  implementation-defined
132       whether  null  terminators,  pointers,  and/or  any alignment bytes are
133       included in this total.
134
135       File descriptors open in the calling process image shall remain open in
136       the  new  process  image,  except  for  those  whose close-on-exec flag
137       FD_CLOEXEC is set.  For those file descriptors that  remain  open,  all
138       attributes  of the open file description remain unchanged. For any file
139       descriptor that is closed for this reason, file locks are removed as  a
140       result  of  the  close  as  described  in  close().  Locks that are not
141       removed by closing of file descriptors remain unchanged.
142
143       If file descriptor 0, 1, or 2 would otherwise be closed  after  a  suc‐
144       cessful  call  to  one of the exec family of functions, implementations
145       may open an unspecified file for the file descriptor in the new process
146       image.  If  a  standard utility or a conforming application is executed
147       with file descriptor 0 not open for reading or with file  descriptor  1
148       or  2  not  open  for  writing, the environment in which the utility or
149       application is executed shall  be  deemed  non-conforming,  and  conse‐
150       quently  the  utility  or  application might not behave as described in
151       this standard.
152
153       Directory streams open in the calling process image shall be closed  in
154       the new process image.
155
156       The  state  of  the floating-point environment in the initial thread of
157       the new process image shall be set to the default.
158
159       The state of conversion descriptors and message catalog descriptors  in
160       the new process image is undefined.
161
162       For the new process image, the equivalent of:
163
164
165           setlocale(LC_ALL, "C")
166
167       shall be executed at start-up.
168
169       Signals  set  to  the  default  action (SIG_DFL) in the calling process
170       image shall be set to the default action  in  the  new  process  image.
171       Except  for SIGCHLD, signals set to be ignored (SIG_IGN) by the calling
172       process image shall be set to be ignored by the new process image. Sig‐
173       nals  set to be caught by the calling process image shall be set to the
174       default action in the new process image (see <signal.h>).
175
176       If the SIGCHLD signal is set to  be  ignored  by  the  calling  process
177       image,  it  is  unspecified  whether  the  SIGCHLD  signal is set to be
178       ignored or to the default action in the new process image.
179
180       After a successful call to any of the exec functions, alternate  signal
181       stacks  are  not preserved and the SA_ONSTACK flag shall be cleared for
182       all signals.
183
184       After a successful call to any of the  exec  functions,  any  functions
185       previously registered by the atexit() or pthread_atfork() functions are
186       no longer registered.
187
188       If the ST_NOSUID bit is set for the  file  system  containing  the  new
189       process  image  file,  then  the effective user ID, effective group ID,
190       saved set-user-ID, and saved set-group-ID  are  unchanged  in  the  new
191       process  image.  Otherwise,  if  the  set-user-ID  mode  bit of the new
192       process image file is set, the effective user ID  of  the  new  process
193       image  shall be set to the user ID of the new process image file. Simi‐
194       larly, if the set-group-ID mode bit of the new process  image  file  is
195       set,  the  effective  group ID of the new process image shall be set to
196       the group ID of the new process image file.  The  real  user  ID,  real
197       group  ID,  and  supplementary group IDs of the new process image shall
198       remain the same as those of the calling process  image.  The  effective
199       user  ID and effective group ID of the new process image shall be saved
200       (as the saved set-user-ID  and  the  saved  set-group-ID)  for  use  by
201       setuid().
202
203       Any  shared memory segments attached to the calling process image shall
204       not be attached to the new process image.
205
206       Any named semaphores open in the calling process shall be closed as  if
207       by appropriate calls to sem_close().
208
209       Any  blocks of typed memory that were mapped in the calling process are
210       unmapped, as if munmap() was implicitly called to unmap them.
211
212       Memory locks established by the calling process via calls to mlockall()
213       or  mlock()  shall  be removed. If locked pages in the address space of
214       the calling process are also mapped into the address  spaces  of  other
215       processes  and  are locked by those processes, the locks established by
216       the other processes shall be unaffected by the call by this process  to
217       the  exec  function.  If  the exec function fails, the effect on memory
218       locks is unspecified.
219
220       Memory mappings created in the process are unmapped before the  address
221       space is rebuilt for the new process image.
222
223       When  the  calling process image does not use the SCHED_FIFO, SCHED_RR,
224       or SCHED_SPORADIC scheduling policies, the scheduling policy and param‐
225       eters  of  the  new  process  image  and the initial thread in that new
226       process image are implementation-defined.
227
228       When the calling  process  image  uses  the  SCHED_FIFO,  SCHED_RR,  or
229       SCHED_SPORADIC  scheduling  policies, the process policy and scheduling
230       parameter settings shall not be changed by a call to an exec  function.
231       The  initial  thread in the new process image shall inherit the process
232       scheduling policy and parameters. It shall have the default system con‐
233       tention scope, but shall inherit its allocation domain from the calling
234       process image.
235
236       Per-process timers created by the  calling  process  shall  be  deleted
237       before replacing the current process image with the new process image.
238
239       All  open  message  queue  descriptors  in the calling process shall be
240       closed, as described in mq_close().
241
242       Any outstanding asynchronous I/O  operations  may  be  canceled.  Those
243       asynchronous  I/O operations that are not canceled shall complete as if
244       the exec function had not yet occurred, but any associated signal noti‐
245       fications shall be suppressed. It is unspecified whether the exec func‐
246       tion itself blocks awaiting such I/O completion. In no event,  however,
247       shall the new process image created by the exec function be affected by
248       the presence of outstanding asynchronous I/O operations at the time the
249       exec function is called. Whether any I/O is canceled, and which I/O may
250       be canceled upon exec, is implementation-defined.
251
252       The new process image shall inherit the CPU-time clock of  the  calling
253       process  image.  This inheritance means that the process CPU-time clock
254       of the process being exec-ed shall not be reinitialized or altered as a
255       result of the exec function other than to reflect the time spent by the
256       process executing the exec function itself.
257
258       The initial value of the CPU-time clock of the initial  thread  of  the
259       new process image shall be set to zero.
260
261       If  the  calling  process  is being traced, the new process image shall
262       continue to be traced into  the  same  trace  stream  as  the  original
263       process  image, but the new process image shall not inherit the mapping
264       of trace event names to trace event type identifiers that  was  defined
265       by     calls     to     the     posix_trace_eventid_open()    or    the
266       posix_trace_trid_eventid_open() functions in the calling process image.
267
268       If the calling process is a trace controller process, any trace streams
269       that  were  created  by  the  calling  process  shall  be  shut down as
270       described in the posix_trace_shutdown() function.
271
272       The thread ID of the initial thread in the new process image is unspec‐
273       ified.
274
275       The  size  and location of the stack on which the initial thread in the
276       new process image runs is unspecified.
277
278       The initial thread in the new process image shall have its cancellation
279       type  set  to PTHREAD_CANCEL_DEFERRED and its cancellation state set to
280       PTHREAD_CANCEL_ENABLED.
281
282       The initial thread in the new process image shall have all  thread-spe‐
283       cific  data  values set to NULL and all thread-specific data keys shall
284       be removed by the call to exec without running destructors.
285
286       The initial thread in the new process image shall be  joinable,  as  if
287       created with the detachstate attribute set to PTHREAD_CREATE_JOINABLE.
288
289       The  new  process  shall inherit at least the following attributes from
290       the calling process image:
291
292        *  Nice value (see nice())
293
294        *  semadj values (see semop())
295
296        *  Process ID
297
298        *  Parent process ID
299
300        *  Process group ID
301
302        *  Session membership
303
304        *  Real user ID
305
306        *  Real group ID
307
308        *  Supplementary group IDs
309
310        *  Time left until an alarm clock signal (see alarm())
311
312        *  Current working directory
313
314        *  Root directory
315
316        *  File mode creation mask (see umask())
317
318        *  File size limit (see getrlimit() and setrlimit())
319
320        *  Process signal mask (see pthread_sigmask())
321
322        *  Pending signal (see sigpending())
323
324        *  tms_utime, tms_stime, tms_cutime, and tms_cstime (see times())
325
326        *  Resource limits
327
328        *  Controlling terminal
329
330        *  Interval timers
331
332       The initial thread of the new process shall inherit at least  the  fol‐
333       lowing attributes from the calling thread:
334
335        *  Signal mask (see sigprocmask() and pthread_sigmask())
336
337        *  Pending signals (see sigpending())
338
339       All  other  process  attributes  defined in this volume of POSIX.1‐2017
340       shall be inherited in the new process image from the old process image.
341       All  other  thread  attributes  defined  in this volume of POSIX.1‐2017
342       shall be inherited in the initial thread in the new process image  from
343       the  calling  thread  in  the  old  process  image.  The inheritance of
344       process or thread attributes not defined by this volume of POSIX.1‐2017
345       is implementation-defined.
346
347       A  call  to  any exec function from a process with more than one thread
348       shall result in all threads being terminated  and  the  new  executable
349       image  being  loaded  and  executed. No destructor functions or cleanup
350       handlers shall be called.
351
352       Upon successful completion, the exec functions shall  mark  for  update
353       the  last data access timestamp of the file. If an exec function failed
354       but was able to locate the process image file, whether  the  last  data
355       access  timestamp  is marked for update is unspecified. Should the exec
356       function succeed, the process image file shall be  considered  to  have
357       been opened with open().  The corresponding close() shall be considered
358       to occur at a time after this open, but before process  termination  or
359       successful  completion  of  a  subsequent call to one of the exec func‐
360       tions, posix_spawn(), or posix_spawnp().  The argv[] and envp[]  arrays
361       of  pointers  and  the strings to which those arrays point shall not be
362       modified by a call to one of the exec functions,  except  as  a  conse‐
363       quence of replacing the process image.
364
365       The saved resource limits in the new process image are set to be a copy
366       of the process' corresponding hard and soft limits.
367

RETURN VALUE

369       If one of the exec functions returns to the calling process  image,  an
370       error  has  occurred;  the return value shall be -1, and errno shall be
371       set to indicate the error.
372

ERRORS

374       The exec functions shall fail if:
375
376       E2BIG  The number of bytes used by the  new  process  image's  argument
377              list  and  environment  list  is greater than the system-imposed
378              limit of {ARG_MAX} bytes.
379
380       EACCES The new process image file is not a regular file and the  imple‐
381              mentation does not support execution of files of its type.
382
383       EINVAL The  new process image file has appropriate privileges and has a
384              recognized executable binary format, but  the  system  does  not
385              support execution of a file with this format.
386
387       The exec functions, except for fexecve(), shall fail if:
388
389       EACCES Search  permission  is  denied for a directory listed in the new
390              process image file's path prefix, or the new process image  file
391              denies execution permission.
392
393       ELOOP  A loop exists in symbolic links encountered during resolution of
394              the path or file argument.
395
396       ENAMETOOLONG
397              The  length  of  a  component  of  a  pathname  is  longer  than
398              {NAME_MAX}.
399
400       ENOENT A  component  of  path or file does not name an existing file or
401              path or file is an empty string.
402
403       ENOTDIR
404              A component of the new process image file's path prefix names an
405              existing file that is neither a directory nor a symbolic link to
406              a directory, or the new process image file's  pathname  contains
407              at  least  one  non-<slash>  character and ends with one or more
408              trailing <slash> characters  and  the  last  pathname  component
409              names  an  existing  file that is neither a directory nor a sym‐
410              bolic link to a directory.
411
412       The exec functions, except for execlp() and execvp(), shall fail if:
413
414       ENOEXEC
415              The new process image file has the appropriate access permission
416              but has an unrecognized format.
417
418       The fexecve() function shall fail if:
419
420       EBADF  The  fd argument is not a valid file descriptor open for execut‐
421              ing.
422
423       The exec functions may fail if:
424
425       ENOMEM The new process image requires more memory than  is  allowed  by
426              the hardware or system-imposed memory management constraints.
427
428       The exec functions, except for fexecve(), may fail if:
429
430       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
431              resolution of the path or file argument.
432
433       ENAMETOOLONG
434              The length of the path argument or the length  of  the  pathname
435              constructed  from the file argument exceeds {PATH_MAX}, or path‐
436              name resolution of a  symbolic  link  produced  an  intermediate
437              result with a length that exceeds {PATH_MAX}.
438
439       ETXTBSY
440              The  new  process  image  file is a pure procedure (shared text)
441              file that is currently open for writing by some process.
442
443       The following sections are informative.
444

EXAMPLES

446   Using execl()
447       The following example executes the ls command, specifying the  pathname
448       of  the  executable  (/bin/ls) and using arguments supplied directly to
449       the command to produce single-column output.
450
451
452           #include <unistd.h>
453
454           int ret;
455           ...
456           ret = execl ("/bin/ls", "ls", "-1", (char *)0);
457
458   Using execle()
459       The following example is similar to Using  execl().   In  addition,  it
460       specifies the environment for the new process image using the env argu‐
461       ment.
462
463
464           #include <unistd.h>
465
466           int ret;
467           char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
468           ...
469           ret = execle ("/bin/ls", "ls", "-l", (char *)0, env);
470
471   Using execlp()
472       The following example searches for the location of the ls command among
473       the directories specified by the PATH environment variable.
474
475
476           #include <unistd.h>
477
478           int ret;
479           ...
480           ret = execlp ("ls", "ls", "-l", (char *)0);
481
482   Using execv()
483       The  following  example  passes  arguments to the ls command in the cmd
484       array.
485
486
487           #include <unistd.h>
488
489           int ret;
490           char *cmd[] = { "ls", "-l", (char *)0 };
491           ...
492           ret = execv ("/bin/ls", cmd);
493
494   Using execve()
495       The following example passes arguments to the ls  command  in  the  cmd
496       array,  and  specifies  the environment for the new process image using
497       the env argument.
498
499
500           #include <unistd.h>
501
502           int ret;
503           char *cmd[] = { "ls", "-l", (char *)0 };
504           char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
505           ...
506           ret = execve ("/bin/ls", cmd, env);
507
508   Using execvp()
509       The following example searches for the location of the ls command among
510       the  directories specified by the PATH environment variable, and passes
511       arguments to the ls command in the cmd array.
512
513
514           #include <unistd.h>
515
516           int ret;
517           char *cmd[] = { "ls", "-l", (char *)0 };
518           ...
519           ret = execvp ("ls", cmd);
520

APPLICATION USAGE

522       As the state of conversion descriptors and message catalog  descriptors
523       in  the  new process image is undefined, conforming applications should
524       not rely on their use and should close them prior to calling one of the
525       exec functions.
526
527       Applications  that  require  other than the default POSIX locale as the
528       global locale in the new process image should call setlocale() with the
529       appropriate parameters.
530
531       When assigning a new value to the environ variable, applications should
532       ensure that the environment to which it will point  contains  at  least
533       the following:
534
535        1. Any implementation-defined variables required by the implementation
536           to provide a conforming environment. See the  _CS_V7_ENV  entry  in
537           <unistd.h> and confstr() for details.
538
539        2. A  value  for  PATH which finds conforming versions of all standard
540           utilities before any other versions.
541
542       The same constraint applies to the envp array  passed  to  execle()  or
543       execve(), in order to ensure that the new process image is invoked in a
544       conforming environment.
545
546       Applications should not execute programs with  file  descriptor  0  not
547       open  for  reading or with file descriptor 1 or 2 not open for writing,
548       as this might cause the executed program to misbehave. In order not  to
549       pass  on  these  file  descriptors to an executed program, applications
550       should not just close them but should  reopen  them  on,  for  example,
551       /dev/null.   Some  implementations  may  reopen them automatically, but
552       applications should not rely on this being done.
553
554       If an application wants to perform a checksum test of  the  file  being
555       executed before executing it, the file will need to be opened with read
556       permission to perform the checksum test.
557
558       Since execute permission is checked by fexecve(), the file  description
559       fd need not have been opened with the O_EXEC flag. However, if the file
560       to be executed denies read and write permission for the process prepar‐
561       ing to do the exec, the only way to provide the fd to fexecve() will be
562       to use the O_EXEC flag when opening fd.  In this case, the  application
563       will  not  be able to perform a checksum test since it will not be able
564       to read the contents of the file.
565
566       Note that when a file descriptor is opened with  O_RDONLY,  O_RDWR,  or
567       O_WRONLY mode, the file descriptor can be used to read, read and write,
568       or write the file, respectively, even if the mode of the  file  changes
569       after  the  file  was  opened. Using the O_EXEC open mode is different;
570       fexecve() will ignore the mode that was used when the  file  descriptor
571       was  opened  and  the exec will fail if the mode of the file associated
572       with fd does not grant execute permission to the calling process at the
573       time fexecve() is called.
574

RATIONALE

576       Early  proposals  required  that  the value of argc passed to main() be
577       ``one or greater''. This was driven by the same requirement  in  drafts
578       of the ISO C standard.  In fact, historical implementations have passed
579       a value of zero when no arguments are supplied to  the  caller  of  the
580       exec  functions.  This  requirement was removed from the ISO C standard
581       and subsequently removed from this volume of POSIX.1‐2017 as well.  The
582       wording,  in particular the use of the word should, requires a Strictly
583       Conforming POSIX Application to pass at least one argument to the  exec
584       function, thus guaranteeing that argc be one or greater when invoked by
585       such an application. In fact, this is good practice, since many  exist‐
586       ing  applications reference argv[0] without first checking the value of
587       argc.
588
589       The requirement on a Strictly Conforming POSIX Application also  states
590       that  the value passed as the first argument be a filename string asso‐
591       ciated with the process being started. Although some existing  applica‐
592       tions  pass  a  pathname  rather than a filename string in some circum‐
593       stances, a filename string is more generally useful, since  the  common
594       usage of argv[0] is in printing diagnostics. In some cases the filename
595       passed is not the actual filename of the file; for example, many imple‐
596       mentations  of  the  login  utility  use  a  convention  of prefixing a
597       <hyphen-minus> ('‐') to the actual filename,  which  indicates  to  the
598       command interpreter being invoked that it is a ``login shell''.
599
600       Also,  note  that the test and [ utilities require specific strings for
601       the argv[0] argument to have deterministic behavior across  all  imple‐
602       mentations.
603
604       Historically,  there  have  been two ways that implementations can exec
605       shell scripts.
606
607       One common historical implementation is that the execl(), execv(), exe‐
608       cle(),  and  execve()  functions return an [ENOEXEC] error for any file
609       not recognizable as executable, including a shell script. When the exe‐
610       clp()  and  execvp()  functions  encounter such a file, they assume the
611       file to be a shell script and invoke a  known  command  interpreter  to
612       interpret  such  files.   This  is  now required by POSIX.1‐2008. These
613       implementations of execvp() and execlp() only give the [ENOEXEC]  error
614       in the rare case of a problem with the command interpreter's executable
615       file. Because of these implementations, the [ENOEXEC] error is not men‐
616       tioned  for  execlp()  or  execvp(), although implementations can still
617       give it.
618
619       Another way that some historical implementations handle  shell  scripts
620       is  by  recognizing  the  first  two bytes of the file as the character
621       string "#!" and using the remainder of the first line of  the  file  as
622       the name of the command interpreter to execute.
623
624       One  potential  source of confusion noted by the standard developers is
625       over how the contents of a process image file affect  the  behavior  of
626       the  exec  family  of  functions. The following is a description of the
627       actions taken:
628
629        1. If the process image file is a valid executable (in a  format  that
630           is executable and valid and having appropriate privileges) for this
631           system, then the system executes the file.
632
633        2. If the process image file has appropriate privileges and  is  in  a
634           format  that is executable but not valid for this system (such as a
635           recognized binary for another architecture), then this is an  error
636           and errno is set to [EINVAL] (see later RATIONALE on [EINVAL]).
637
638        3. If  the  process  image  file has appropriate privileges but is not
639           otherwise recognized:
640
641            a. If this is a call to execlp() or execvp(), then they  invoke  a
642               command  interpreter  assuming that the process image file is a
643               shell script.
644
645            b. If this is not a call to execlp() or execvp(),  then  an  error
646               occurs and errno is set to [ENOEXEC].
647
648       Applications  that do not require to access their arguments may use the
649       form:
650
651
652           main(void)
653
654       as specified in the ISO C standard. However,  the  implementation  will
655       always  provide  the  two arguments argc and argv, even if they are not
656       used.
657
658       Some implementations provide a third argument to  main()  called  envp.
659       This  is  defined  as  a pointer to the environment. The ISO C standard
660       specifies invoking main() with two arguments, so  implementations  must
661       support   applications   written   this   way.  Since  this  volume  of
662       POSIX.1‐2017 defines the global variable environ, which  is  also  pro‐
663       vided  by historical implementations and can be used anywhere that envp
664       could be used, there is no  functional  need  for  the  envp  argument.
665       Applications should use the getenv() function rather than accessing the
666       environment directly via either envp or environ.   Implementations  are
667       required  to  support  the two-argument calling sequence, but this does
668       not prohibit an implementation from  supporting  envp  as  an  optional
669       third argument.
670
671       This  volume  of  POSIX.1‐2017  specifies  that  signals set to SIG_IGN
672       remain set to SIG_IGN, and that the new process image inherits the sig‐
673       nal  mask of the thread that called exec in the old process image. This
674       is consistent with historical implementations, and it permits some use‐
675       ful  functionality,  such  as  the nohup command. However, it should be
676       noted that many existing applications wrongly assume  that  they  start
677       with  certain  signals  set  to the default action and/or unblocked. In
678       particular, applications written with a simpler signal model that  does
679       not include blocking of signals, such as the one in the ISO C standard,
680       may not behave properly if invoked with some  signals  blocked.  There‐
681       fore,  it  is  best not to block or ignore signals across execs without
682       explicit reason to do so, and especially not to  block  signals  across
683       execs of arbitrary (not closely cooperating) programs.
684
685       The  exec  functions always save the value of the effective user ID and
686       effective group ID of the  process  at  the  completion  of  the  exec,
687       whether  or  not the set-user-ID or the set-group-ID bit of the process
688       image file is set.
689
690       The statement about argv[] and envp[] being constants  is  included  to
691       make explicit to future writers of language bindings that these objects
692       are completely constant. Due to a limitation of the ISO C standard,  it
693       is not possible to state that idea in standard C. Specifying two levels
694       of const-qualification for the argv[] and  envp[]  parameters  for  the
695       exec  functions  may  seem  to  be the natural choice, given that these
696       functions do not modify either the array of pointers or the  characters
697       to  which the function points, but this would disallow existing correct
698       code.  Instead, only the array of pointers is noted  as  constant.  The
699       table  of  assignment  compatibility for dst=src derived from the ISO C
700       standard summarizes the compatibility:
701
702┌────────────────────┬──────────┬────────────────┬───────────────┬─────────────────────┐
703dst: │ char *[] const char *[] char *const[] const char *const[] 
704├────────────────────┼──────────┼────────────────┼───────────────┼─────────────────────┤
705src:                │          │                │               │                     │
706char *[]            │  VALID   │       —        │     VALID     │          —          │
707const char *[]      │    —     │     VALID      │       —       │        VALID        │
708char * const []     │    —     │       —        │     VALID     │          —          │
709const char *const[] │    —     │       —        │       —       │        VALID        │
710└────────────────────┴──────────┴────────────────┴───────────────┴─────────────────────┘
711       Since all existing code has a source type matching the first  row,  the
712       column  that gives the most valid combinations is the third column. The
713       only other possibility is the fourth column, but using it would require
714       a cast on the argv or envp arguments. It is unfortunate that the fourth
715       column cannot be used, because the declaration a non-expert would natu‐
716       rally use would be that in the second row.
717
718       The  ISO C  standard and this volume of POSIX.1‐2017 do not conflict on
719       the use of environ, but some historical implementations of environ  may
720       cause  a  conflict. As long as environ is treated in the same way as an
721       entry point (for example, fork()), it conforms  to  both  standards.  A
722       library  can  contain  fork(),  but if there is a user-provided fork(),
723       that fork() is given precedence and no problem ensues. The situation is
724       similar  for  environ: the definition in this volume of POSIX.1‐2017 is
725       to be used if there is no user-provided environ to take precedence.  At
726       least three implementations are known to exist that solve this problem.
727
728       E2BIG  The limit {ARG_MAX} applies not just to the size of the argument
729              list, but to the sum of that and the  size  of  the  environment
730              list.
731
732       EFAULT Some  historical  systems  return [EFAULT] rather than [ENOEXEC]
733              when the new process image file is corrupted. They are  non-con‐
734              forming.
735
736       EINVAL This  error  condition  was  added  to  POSIX.1‐2008 to allow an
737              implementation to detect executable files generated for  differ‐
738              ent  architectures,  and indicate this situation to the applica‐
739              tion. Historical implementations of shells, execvp(),  and  exe‐
740              clp()  that encounter an [ENOEXEC] error will execute a shell on
741              the assumption that the file is a shell script.  This  will  not
742              produce  the  desired effect when the file is a valid executable
743              for a different architecture. An implementation may  now  choose
744              to  avoid  this  problem by returning [EINVAL] when a valid exe‐
745              cutable for a different architecture is encountered.  Some  his‐
746              torical  implementations  return  [EINVAL]  to indicate that the
747              path argument contains a character with the high order bit  set.
748              The  standard  developers chose to deviate from historical prac‐
749              tice for the following reasons:
750
751                    1. The new utilization of [EINVAL] will provide some  mea‐
752                       sure of utility to the user community.
753
754                    2. Historical  use  of  [EINVAL]  is  not acceptable in an
755                       internationalized operating environment.
756
757       ENAMETOOLONG
758              Since the file pathname may be constructed by taking elements in
759              the  PATH  variable and putting them together with the filename,
760              the [ENAMETOOLONG] error condition could also  be  reached  this
761              way.
762
763       ETXTBSY
764              System  V  returns  this  error when the executable file is cur‐
765              rently  open  for  writing  by  some  process.  This  volume  of
766              POSIX.1‐2017 neither requires nor prohibits this behavior.
767
768       Other systems (such as System V) may return [EINTR] from exec.  This is
769       not addressed by this volume of POSIX.1‐2017, but  implementations  may
770       have a window between the call to exec and the time that a signal could
771       cause one of the exec calls to return with [EINTR].
772
773       An explicit statement  regarding  the  floating-point  environment  (as
774       defined  in  the  <fenv.h>  header) was added to make it clear that the
775       floating-point environment is set to its default when a call to one  of
776       the  exec  functions succeeds. The requirements for inheritance or set‐
777       ting to the default for other process and thread start-up functions  is
778       covered  by  more  generic  statements in their descriptions and can be
779       summarized as follows:
780
781       posix_spawn() Set to default.
782
783       fork()        Inherit.
784
785       pthread_create()
786                     Inherit.
787
788       The purpose of the fexecve() function is to  enable  executing  a  file
789       which  has  been  verified  to  be the intended file. It is possible to
790       actively check the file by reading from the file descriptor and be sure
791       that  the file is not exchanged for another between the reading and the
792       execution. Alternatively, a function like openat() can be used to  open
793       a file which has been found by reading the content of a directory using
794       readdir().
795

FUTURE DIRECTIONS

797       None.
798

SEE ALSO

800       alarm(), atexit(), chmod(), close(), confstr(), exit(), fcntl(),
801       fork(), fstatvfs(), getenv(), getitimer(), getrlimit(), mknod(),
802       mmap(), nice(), open(), posix_spawn(), posix_trace_create(),
803       posix_trace_event(), posix_trace_eventid_equal(), pthread_atfork(),
804       pthread_sigmask(), putenv(), readdir(), semop(), setlocale(), shmat(),
805       sigaction(), sigaltstack(), sigpending(), system(), times(), ulimit(),
806       umask()
807
808       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
809       Variables, <unistd.h>
810
811       The Shell and Utilities volume of POSIX.1‐2017, test
812
814       Portions  of  this text are reprinted and reproduced in electronic form
815       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
816       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
817       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
818       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
819       event of any discrepancy between this version and the original IEEE and
820       The  Open Group Standard, the original IEEE and The Open Group Standard
821       is the referee document. The original Standard can be  obtained  online
822       at http://www.opengroup.org/unix/online.html .
823
824       Any  typographical  or  formatting  errors that appear in this page are
825       most likely to have been introduced during the conversion of the source
826       files  to  man page format. To report such errors, see https://www.ker
827       nel.org/doc/man-pages/reporting_bugs.html .
828
829
830
831IEEE/The Open Group                  2017                             EXEC(3P)
Impressum