1EXEC(3P) POSIX Programmer's Manual EXEC(3P)
2
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
12 environ, execl, execle, execlp, execv, execve, execvp, fexecve — exe‐
13 cute a file
14
16 #include <unistd.h>
17 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
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 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 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 int main (int argc, char *argv[]);
45 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 extern char **environ;
52 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 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 Any application that directly modifies the pointers to which the envi‐
68 ron variable points has undefined behavior.
69 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 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 The argument path points to a pathname that identifies the new process
81 image file.
82 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 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 execl(<shell path>, arg0, file, arg1, ..., (char *)0);
103 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 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 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 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 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 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 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 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 Directory streams open in the calling process image shall be closed in
154 the new process image.
155 The state of the floating-point environment in the initial thread of
157 the new process image shall be set to the default.
158 The state of conversion descriptors and message catalog descriptors in
160 the new process image is undefined.
161 For the new process image, the equivalent of:
163 setlocale(LC_ALL, "C")
166 shall be executed at start-up.
168 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 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 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 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 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 Any shared memory segments attached to the calling process image shall
204 not be attached to the new process image.
205 Any named semaphores open in the calling process shall be closed as if
207 by appropriate calls to sem_close().
208 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 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 Memory mappings created in the process are unmapped before the address
221 space is rebuilt for the new process image.
222 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 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 Per-process timers created by the calling process shall be deleted
237 before replacing the current process image with the new process image.
238 All open message queue descriptors in the calling process shall be
240 closed, as described in mq_close().
241 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 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 The initial value of the CPU-time clock of the initial thread of the
259 new process image shall be set to zero.
260 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 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 The thread ID of the initial thread in the new process image is unspec‐
273 ified.
274 The size and location of the stack on which the initial thread in the
276 new process image runs is unspecified.
277 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 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 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 The new process shall inherit at least the following attributes from
290 the calling process image:
291 * Nice value (see nice())
293 * semadj values (see semop())
295 * Process ID
297 * Parent process ID
299 * Process group ID
301 * Session membership
303 * Real user ID
305 * Real group ID
307 * Supplementary group IDs
309 * Time left until an alarm clock signal (see alarm())
311 * Current working directory
313 * Root directory
315 * File mode creation mask (see umask())
317 * File size limit (see getrlimit() and setrlimit())
319 * Process signal mask (see pthread_sigmask())
321 * Pending signal (see sigpending())
323 * tms_utime, tms_stime, tms_cutime, and tms_cstime (see times())
325 * Resource limits
327 * Controlling terminal
329 * Interval timers
331 The initial thread of the new process shall inherit at least the fol‐
333 lowing attributes from the calling thread:
334 * Signal mask (see sigprocmask() and pthread_sigmask())
336 * Pending signals (see sigpending())
338 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 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 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 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
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
374 The exec functions shall fail if:
375 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 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 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 The exec functions, except for fexecve(), shall fail if:
388 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 ELOOP A loop exists in symbolic links encountered during resolution of
394 the path or file argument.
395 ENAMETOOLONG
397 The length of a component of a pathname is longer than
398 {NAME_MAX}.
399 ENOENT A component of path or file does not name an existing file or
401 path or file is an empty string.
402 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 The exec functions, except for execlp() and execvp(), shall fail if:
413 ENOEXEC
415 The new process image file has the appropriate access permission
416 but has an unrecognized format.
417 The fexecve() function shall fail if:
419 EBADF The fd argument is not a valid file descriptor open for execut‐
421 ing.
422 The exec functions may fail if:
424 ENOMEM The new process image requires more memory than is allowed by
426 the hardware or system-imposed memory management constraints.
427 The exec functions, except for fexecve(), may fail if:
429 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
431 resolution of the path or file argument.
432 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 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 The following sections are informative.
444
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 #include <unistd.h>
453 int ret;
455 ...
456 ret = execl ("/bin/ls", "ls", "-1", (char *)0);
457 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 #include <unistd.h>
465 int ret;
467 char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
468 ...
469 ret = execle ("/bin/ls", "ls", "-l", (char *)0, env);
470 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 #include <unistd.h>
477 int ret;
479 ...
480 ret = execlp ("ls", "ls", "-l", (char *)0);
481 Using execv()
483 The following example passes arguments to the ls command in the cmd
484 array.
485 #include <unistd.h>
488 int ret;
490 char *cmd[] = { "ls", "-l", (char *)0 };
491 ...
492 ret = execv ("/bin/ls", cmd);
493 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 #include <unistd.h>
501 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 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 #include <unistd.h>
515 int ret;
517 char *cmd[] = { "ls", "-l", (char *)0 };
518 ...
519 ret = execvp ("ls", cmd);
520
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 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 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 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 2. A value for PATH which finds conforming versions of all standard
540 utilities before any other versions.
541 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 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 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 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 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
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 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 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 Historically, there have been two ways that implementations can exec
605 shell scripts.
606 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 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 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 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 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 3. If the process image file has appropriate privileges but is not
639 otherwise recognized:
640 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 b. If this is not a call to execlp() or execvp(), then an error
646 occurs and errno is set to [ENOEXEC].
647 Applications that do not require to access their arguments may use the
649 form:
650 main(void)
653 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 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 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 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 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┌────────────────────┬──────────┬────────────────┬───────────────┬─────────────────────┐
703│ dst: │ char *[] │ const char *[] │ char *const[] │ const char *const[] │
704├────────────────────┼──────────┼────────────────┼───────────────┼─────────────────────┤
705│src: │ │ │ │ │
706│char *[] │ VALID │ — │ VALID │ — │
707│const char *[] │ — │ VALID │ — │ VALID │
708│char * const [] │ — │ — │ VALID │ — │
709│const 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 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 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 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 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 1. The new utilization of [EINVAL] will provide some mea‐
752 sure of utility to the user community.
753 2. Historical use of [EINVAL] is not acceptable in an
755 internationalized operating environment.
756 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 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 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 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 posix_spawn() Set to default.
782 fork() Inherit.
784 pthread_create()
786 Inherit.
787 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
797 None.
798
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 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
809 Variables, <unistd.h>
810 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 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 .
828IEEE/The Open Group 2017 EXEC(3P)