diff options
Diffstat (limited to 'upstream/archlinux/man3p/exec.3p')
| -rw-r--r-- | upstream/archlinux/man3p/exec.3p | 1357 |
1 files changed, 1357 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/exec.3p b/upstream/archlinux/man3p/exec.3p new file mode 100644 index 00000000..552724a3 --- /dev/null +++ b/upstream/archlinux/man3p/exec.3p @@ -0,0 +1,1357 @@ +'\" et +.TH EXEC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +environ, +execl, +execle, +execlp, +execv, +execve, +execvp, +fexecve +\(em execute a file +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +extern char **environ; +int execl(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execle(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, + (char *)0, char *const \fIenvp\fP[]*/); +int execlp(const char *\fIfile\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execv(const char *\fIpath\fP, char *const \fIargv\fP[]); +int execve(const char *\fIpath\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +int execvp(const char *\fIfile\fP, char *const \fIargv\fP[]); +int fexecve(int \fIfd\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +.fi +.SH DESCRIPTION +The +.IR exec +family of functions shall replace the current process image with a new +process image. The new image shall be constructed from a regular, +executable file called the +.IR "new process image file" . +There shall be no return from a successful +.IR exec , +because the calling process image is overlaid by the new process +image. +.P +The +\fIfexecve\fR() +function shall be equivalent to the +\fIexecve\fR() +function except that the file to be executed is determined by the file +descriptor +.IR fd +instead of a pathname. The file offset of +.IR fd +is ignored. +.P +When a C-language program is executed as a result of a call to one +of the +.IR exec +family of functions, it shall be entered as a C-language function call +as follows: +.sp +.RS 4 +.nf + +int main (\fIint argc, char *argv\fP[]); +.fi +.P +.RE +.P +where +.IR argc +is the argument count and +.IR argv +is an array of character pointers to the arguments themselves. +In addition, the following variable, which must be declared by the user +if it is to be used directly: +.sp +.RS 4 +.nf + +extern char **environ; +.fi +.P +.RE +.P +is initialized as a pointer to an array of character pointers to the +environment strings. The +.IR argv +and +.IR environ +arrays are each terminated by a null pointer. The null pointer +terminating the +.IR argv +array is not counted in +.IR argc . +.P +Applications can change the entire environment in a single operation by +assigning the +.IR environ +variable to point to an array of character pointers to the new environment +strings. After assigning a new value to +.IR environ , +applications should not rely on the new environment strings remaining +part of the environment, as a call to +\fIgetenv\fR(), +\fIputenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or any function that is dependent on an environment variable may, on +noticing that +.IR environ +has changed, copy the environment strings to a new array and assign +.IR environ +to point to it. +.P +Any application that directly modifies the pointers to which the +.IR environ +variable points has undefined behavior. +.P +Conforming multi-threaded applications shall not use the +.IR environ +variable to access or modify any environment variable while any other +thread is concurrently modifying any environment variable. A call to +any function dependent on any environment variable shall be considered +a use of the +.IR environ +variable to access that environment variable. +.P +The arguments specified by a program with one of the +.IR exec +functions shall be passed on to the new process image in the +corresponding +\fImain\fR() +arguments. +.P +The argument +.IR path +points to a pathname that identifies the new process image file. +.P +The argument +.IR file +is used to construct a pathname that identifies the new process image +file. If the +.IR file +argument contains a +<slash> +character, the +.IR file +argument shall be used as the pathname for this file. Otherwise, the +path prefix for this file is obtained by a search of the directories +passed as the environment variable +.IR PATH +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables"). +If this environment variable is not present, the results +of the search are implementation-defined. +.P +There are two distinct ways in which the contents of the process image +file may cause the execution to fail, distinguished by the setting of +.IR errno +to either +.BR [ENOEXEC] +or +.BR [EINVAL] +(see the ERRORS section). In the cases where the other members of the +.IR exec +family of functions would fail and set +.IR errno +to +.BR [ENOEXEC] , +the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions shall execute a command interpreter and the environment of the +executed command shall be as if the process invoked the +.IR sh +utility using +\fIexecl\fR() +as follows: +.sp +.RS 4 +.nf + +execl(<shell path>, arg0, file, arg1, ..., (char *)0); +.fi +.P +.RE +.P +where <\fIshell\ path\fP> is an unspecified pathname for the +.IR sh +utility, +.IR file +is the process image file, and for +\fIexecvp\fR(), +where +.IR arg 0, +.IR arg 1, +and so on correspond to the values passed to +\fIexecvp\fR() +in +.IR argv [0], +.IR argv [1], +and so on. +.P +The arguments represented by +.IR arg0 ,\|.\|.\|. +are pointers to null-terminated character strings. These strings +shall constitute the argument list available to the new process +image. The list is terminated by a null pointer. The argument +.IR arg0 +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR argv +is an array of character pointers to null-terminated strings. The +application shall ensure that the last member of this array is a null +pointer. These strings shall constitute the argument list available to +the new process image. The value in +.IR argv [0] +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR envp +is an array of character pointers to null-terminated strings. These +strings shall constitute the environment for the new process image. +The +.IR envp +array is terminated by a null pointer. +.P +For those forms not containing an +.IR envp +pointer (\c +\fIexecl\fR(), +\fIexecv\fR(), +\fIexeclp\fR(), +and +\fIexecvp\fR()), +the environment for the new process image shall be taken from the +external variable +.IR environ +in the calling process. +.P +The number of bytes available for the new process' combined argument +and environment lists is +{ARG_MAX}. +It is implementation-defined whether null terminators, pointers, +and/or any alignment bytes are included in this total. +.P +File descriptors open in the calling process image shall remain open in +the new process image, except for those whose close-on-\c +.IR exec +flag FD_CLOEXEC is set. +For those file descriptors that remain open, all attributes of the open +file description remain unchanged. For any file descriptor that is +closed for this reason, file locks are removed as a result of the close +as described in +\fIclose\fR(). +Locks that are not removed by closing of file descriptors remain +unchanged. +.P +If file descriptor 0, 1, or 2 would otherwise be closed after a successful +call to one of the +.IR exec +family of functions, implementations may open an unspecified file for +the file descriptor in the new process image. If a standard utility +or a conforming application is executed with file descriptor 0 not +open for reading or with file descriptor 1 or 2 not open for writing, +the environment in which the utility or application is executed shall +be deemed non-conforming, and consequently the utility or application +might not behave as described in this standard. +.P +Directory streams open in the calling process image shall be closed +in the new process image. +.P +The state of the floating-point environment in the initial thread +of the new process image shall be set to the default. +.P +The state of conversion descriptors +and message catalog descriptors in the new process image is undefined. +.P +For the new process image, the equivalent of: +.sp +.RS 4 +.nf + +setlocale(LC_ALL, "C") +.fi +.P +.RE +.P +shall be executed at start-up. +.P +Signals set to the default action (SIG_DFL) in the calling process +image shall be set to the default action in the new process image. +Except for SIGCHLD, signals set to be ignored (SIG_IGN) by the calling +process image shall be set to be +ignored by the new process image. Signals set to be caught by the +calling process image shall be set to the default action in the new +process image (see +.IR <signal.h> ). +.P +If the SIGCHLD signal is set to be ignored by the calling process +image, it is unspecified whether the SIGCHLD signal is set to be +ignored or to the default action in the new process image. +.P +After a successful call to any of the +.IR exec +functions, alternate signal stacks are not preserved and the SA_ONSTACK +flag +shall be cleared for all signals. +.P +After a successful call to any of the +.IR exec +functions, any functions previously registered by the +\fIatexit\fR() +or +\fIpthread_atfork\fR() +functions are no longer registered. +.P +If the ST_NOSUID bit is set for the file system containing the new +process +image file, then the effective user ID, effective group ID, saved +set-user-ID, and saved set-group-ID are unchanged in the new process +image. Otherwise, +if the set-user-ID mode bit of the new process image file is set, the +effective user ID of the new process image shall be set to the user ID +of the new process image file. Similarly, if the set-group-ID mode bit +of the new process image file is set, the effective group ID of the new +process image shall be set to the group ID of the new process image +file. The real user ID, real group ID, and supplementary group IDs of +the new process image shall remain the same as those of the calling +process image. The effective user ID and effective group ID of the new +process image shall be saved (as the saved set-user-ID and the saved +set-group-ID) for use by +\fIsetuid\fR(). +.P +Any shared memory segments attached to the calling process image +shall not be attached to the new process image. +.P +Any named semaphores open in the calling process shall be closed as +if by appropriate calls to +\fIsem_close\fR(). +.P +Any blocks of typed memory that were mapped in the calling process are +unmapped, as if +\fImunmap\fR() +was implicitly called to unmap them. +.P +Memory locks established by the calling process via calls to +\fImlockall\fR() +or +\fImlock\fR() +shall be removed. If locked pages in the address space of the calling +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by the call by this process to the +.IR exec +function. If the +.IR exec +function fails, the effect on memory locks is unspecified. +.P +Memory mappings created in the process are unmapped before the address +space is rebuilt for the new process image. +.P +When the calling process image does not use the SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC +scheduling policies, the scheduling policy and parameters of the +new process image and the initial thread in that new process image are +implementation-defined. +.P +When the calling process image uses the SCHED_FIFO, SCHED_RR, or +SCHED_SPORADIC scheduling policies, the process policy and scheduling +parameter settings shall not be changed by a call to an +.IR exec +function. +The initial thread in the new process image shall inherit the +process scheduling policy and parameters. It shall have the default +system contention scope, but shall inherit its allocation domain +from the calling process image. +.P +Per-process timers created by the calling process shall be deleted before +replacing the current process image with the new process image. +.P +All open message queue descriptors in the calling process shall be closed, +as described in +\fImq_close\fR(). +.P +Any outstanding asynchronous I/O operations may be canceled. Those +asynchronous I/O operations that are not canceled shall complete as if +the +.IR exec +function had not yet occurred, but any associated signal notifications +shall be suppressed. It is unspecified whether the +.IR exec +function itself blocks awaiting such I/O completion. In no event, +however, shall the new process image created by the +.IR exec +function be affected by the presence of outstanding asynchronous I/O +operations at the time the +.IR exec +function is called. Whether any I/O is canceled, and which I/O may be +canceled upon +.IR exec , +is implementation-defined. +.P +The new process image shall inherit the CPU-time clock of the calling +process image. This inheritance means that the process CPU-time clock +of the process being +.IR exec -ed +shall not be reinitialized or altered as a result of the +.IR exec +function other than to reflect the time spent by the process executing +the +.IR exec +function itself. +.P +The initial value of the CPU-time clock of the initial thread of the +new process image shall be set to zero. +.P +If the calling process is being traced, the new process image shall +continue to be traced into the same trace stream as the original +process image, but the new process image shall not inherit the mapping +of trace event names to trace event type identifiers that was defined +by calls to the +\fIposix_trace_eventid_open\fR() +or the +\fIposix_trace_trid_eventid_open\fR() +functions in the calling process image. +.P +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down as +described in the +\fIposix_trace_shutdown\fR() +function. +.P +The thread ID of the initial thread in the new process image is +unspecified. +.P +The size and location of the stack on which the initial thread in the +new process image runs is unspecified. +.P +The initial thread in the new process image shall have its cancellation +type set to PTHREAD_CANCEL_DEFERRED and its cancellation state set to +PTHREAD_CANCEL_ENABLED. +.P +The initial thread in the new process image shall have all +thread-specific data values set to NULL and all thread-specific data +keys shall be removed by the call to +.IR exec +without running destructors. +.P +The initial thread in the new process image shall be joinable, as if +created with the +.IR detachstate +attribute set to PTHREAD_CREATE_JOINABLE. +.P +The new process shall inherit at least the following attributes from +the calling process image: +.IP " *" 4 +Nice value (see +\fInice\fR()) +.IP " *" 4 +\fIsemadj\fP values (see +\fIsemop\fR()) +.IP " *" 4 +Process ID +.IP " *" 4 +Parent process ID +.IP " *" 4 +Process group ID +.IP " *" 4 +Session membership +.IP " *" 4 +Real user ID +.IP " *" 4 +Real group ID +.IP " *" 4 +Supplementary group IDs +.IP " *" 4 +Time left until an alarm clock signal (see +\fIalarm\fR()) +.IP " *" 4 +Current working directory +.IP " *" 4 +Root directory +.IP " *" 4 +File mode creation mask (see +\fIumask\fR()) +.IP " *" 4 +File size limit (see +\fIgetrlimit\fR() +and +\fIsetrlimit\fR()) +.IP " *" 4 +Process signal mask (see +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signal (see +\fIsigpending\fR()) +.IP " *" 4 +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime +(see +\fItimes\fR()) +.IP " *" 4 +Resource limits +.IP " *" 4 +Controlling terminal +.IP " *" 4 +Interval timers +.P +The initial thread of the new process shall inherit at least the +following attributes from the calling thread: +.IP " *" 4 +Signal mask (see +\fIsigprocmask\fR() +and +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signals (see +\fIsigpending\fR()) +.P +All other process attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the +new process image from the old process image. All other thread +attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the initial thread in +the new process image from the calling thread in the old process image. +The inheritance of process or thread attributes not defined by this volume of POSIX.1\(hy2017 is +implementation-defined. +.P +A call to any +.IR exec +function from a process with more than one thread shall result in all +threads being terminated and the new executable image being loaded and +executed. No destructor functions or cleanup handlers shall be called. +.P +Upon successful completion, the +.IR exec +functions shall mark for update the last data access timestamp +of the file. If an +.IR exec +function failed but was able to locate the process image file, whether the +last data access timestamp is marked for update is unspecified. Should the +.IR exec +function succeed, the process image file shall be considered to have been +opened with +\fIopen\fR(). +The corresponding +\fIclose\fR() +shall be considered to occur at a time after this open, but before process +termination or successful completion of a subsequent call to one of the +.IR exec +functions, +\fIposix_spawn\fR(), +or +\fIposix_spawnp\fR(). +The +.IR argv [\|] +and +.IR envp [\|] +arrays of pointers and the strings to which those arrays point shall +not be modified by a call to one of the +.IR exec +functions, except as a consequence of replacing the process image. +.P +The saved resource limits in the new process image are set to be a copy +of the process' corresponding hard and soft limits. +.SH "RETURN VALUE" +If one of the +.IR exec +functions returns to the calling process image, an error has occurred; +the return value shall be \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +.IR exec +functions shall fail if: +.TP +.BR E2BIG +The number of bytes used by the new process image's argument list and +environment list is greater than the system-imposed limit of +{ARG_MAX} +bytes. +.TP +.BR EACCES +The new process image file is not a regular file and the implementation +does not support execution of files of its type. +.TP +.BR EINVAL +The new process image file has appropriate privileges and has a +recognized executable binary format, but the system does not support +execution of a file with this format. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +shall fail if: +.TP +.BR EACCES +Search permission is denied for a directory listed in the new process +image file's path prefix, or the new process image file denies execution +permission. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +or +.IR file +does not name an existing file or +.IR path +or +.IR file +is an empty string. +.TP +.BR ENOTDIR +A component of the new process image file's path prefix names an existing +file that is neither a directory nor a symbolic link to a directory, +or the new process image file's pathname contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.P +The +.IR exec +functions, except for +\fIexeclp\fR() +and +\fIexecvp\fR(), +shall fail if: +.TP +.BR ENOEXEC +The new process image file has the appropriate access permission but +has an unrecognized format. +.P +The +\fIfexecve\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor open for executing. +.P +The +.IR exec +functions may fail if: +.TP +.BR ENOMEM +The new process image requires more memory than is allowed by +the hardware or system-imposed memory management constraints. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path +argument or the length of the pathname constructed from the +.IR file +argument exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate result +with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The new process image file is a pure procedure (shared text) file that +is currently open for writing by some process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using execl(\|)" +.P +The following example executes the +.IR ls +command, specifying the pathname of the executable (\c +.BR /bin/ls ) +and using arguments supplied directly to the command to produce +single-column output. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +\&... +ret = execl ("/bin/ls", "ls", "-1", (char *)0); +.fi +.P +.RE +.SS "Using execle(\|)" +.P +The following example is similar to +.IR "Using execl(\|)". +In addition, it specifies the environment for the new process image +using the +.IR env +argument. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); +.fi +.P +.RE +.SS "Using execlp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +\&... +ret = execlp ("ls", "ls", "-l", (char *)0); +.fi +.P +.RE +.SS "Using execv(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execv ("/bin/ls", cmd); +.fi +.P +.RE +.SS "Using execve(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array, and specifies the environment for the new process image using the +.IR env +argument. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execve ("/bin/ls", cmd, env); +.fi +.P +.RE +.SS "Using execvp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable, and passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf + +#include <unistd.h> +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execvp ("ls", cmd); +.fi +.P +.RE +.SH "APPLICATION USAGE" +As the state of conversion descriptors and message catalog +descriptors in the new process image is undefined, conforming +applications should not rely on their use and should close them prior +to calling one of the +.IR exec +functions. +.P +Applications that require other than the default POSIX locale as the +global locale in the new process image should call +\fIsetlocale\fR() +with the appropriate parameters. +.P +When assigning a new value to the +.IR environ +variable, applications should ensure that the environment to which it +will point contains at least the following: +.IP " 1." 4 +Any implementation-defined variables required by the implementation to +provide a conforming environment. See the _CS_V7_ENV entry in +.IR <unistd.h> +and +\fIconfstr\fR() +for details. +.IP " 2." 4 +A value for +.IR PATH +which finds conforming versions of all standard utilities before any +other versions. +.P +The same constraint applies to the +.IR envp +array passed to +\fIexecle\fR() +or +\fIexecve\fR(), +in order to ensure that the new process image is invoked in a conforming +environment. +.P +Applications should not execute programs with file descriptor 0 not open +for reading or with file descriptor 1 or 2 not open for writing, as this +might cause the executed program to misbehave. In order not to pass on +these file descriptors to an executed program, applications should not +just close them but should reopen them on, for example, +.BR /dev/null . +Some implementations may reopen them automatically, but applications +should not rely on this being done. +.P +If an application wants to perform a checksum test of the file being +executed before executing it, the file will need to be opened with read +permission to perform the checksum test. +.P +Since execute permission is checked by +\fIfexecve\fR(), +the file description +.IR fd +need not have been opened with the O_EXEC flag. However, if the file +to be executed denies read and write permission for the process +preparing to do the +.IR exec , +the only way to provide the +.IR fd +to +\fIfexecve\fR() +will be to use the O_EXEC flag when opening +.IR fd . +In this case, the application will not be able to perform a checksum +test since it will not be able to read the contents of the file. +.P +Note that when a file descriptor is opened with O_RDONLY, O_RDWR, or +O_WRONLY mode, the file descriptor can be used to read, read and write, +or write the file, respectively, even if the mode of the file changes +after the file was opened. Using the O_EXEC open mode is different; +\fIfexecve\fR() +will ignore the mode that was used when the file descriptor was opened +and the +.IR exec +will fail if the mode of the file associated with +.IR fd +does not grant execute permission to the calling process at the time +\fIfexecve\fR() +is called. +.SH RATIONALE +Early proposals required that the value of +.IR argc +passed to +\fImain\fR() +be ``one or greater''. This was driven by the same requirement in +drafts of the ISO\ C standard. +In fact, historical implementations have passed a value of zero when no +arguments are supplied to the caller of the +.IR exec +functions. This requirement was removed from the ISO\ C standard and subsequently +removed from this volume of POSIX.1\(hy2017 as well. The wording, in particular the use of the +word \fIshould\fP, requires a Strictly Conforming POSIX Application +to pass at least one argument to the +.IR exec +function, thus guaranteeing that +.IR argc +be one or greater when invoked by such an application. In fact, this is +good practice, since many existing applications reference +.IR argv [0] +without first checking the value of +.IR argc . +.P +The requirement on a Strictly Conforming POSIX Application also states +that the value passed as the first argument be a filename string +associated with the process being started. Although some existing +applications pass a pathname rather than a filename string in some +circumstances, a filename string is more generally useful, since the +common usage of +.IR argv [0] +is in printing diagnostics. In some cases the filename passed is not +the actual filename of the file; for example, many implementations of the +.IR login +utility use a convention of prefixing a +<hyphen-minus> +(\c +.BR '\(hy' ) +to the actual filename, which indicates to the command interpreter being +invoked that it is a ``login shell''. +.P +Also, note that the +.IR test +and +.IR [ +utilities require specific strings for the +.IR argv [0] +argument to have deterministic behavior across all implementations. +.P +Historically, there have been two ways that implementations can +.IR exec +shell scripts. +.P +One common historical implementation is that the +\fIexecl\fR(), +\fIexecv\fR(), +\fIexecle\fR(), +and +\fIexecve\fR() +functions return an +.BR [ENOEXEC] +error for any file not recognizable as executable, including a shell +script. When the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions encounter such a file, they assume the file to be a shell +script and invoke a known command interpreter to interpret such files. +This is now required by POSIX.1\(hy2008. These implementations of +\fIexecvp\fR() +and +\fIexeclp\fR() +only give the +.BR [ENOEXEC] +error in the rare case of a problem with the command interpreter's +executable file. Because of these implementations, the +.BR [ENOEXEC] +error is not mentioned for +\fIexeclp\fR() +or +\fIexecvp\fR(), +although implementations can still give it. +.P +Another way that some historical implementations handle shell scripts +is by recognizing the first two bytes of the file as the character +string +.BR \(dq#!\(dq +and using the remainder of the first line of the file as the name of +the command interpreter to execute. +.P +One potential source of confusion noted by the standard developers +is over how the contents of a process image file affect the behavior +of the +.IR exec +family of functions. The following is a description of the actions +taken: +.IP " 1." 4 +If the process image file is a valid executable (in a format that is +executable and valid and having appropriate privileges) for this +system, then the system executes the file. +.IP " 2." 4 +If the process image file has appropriate privileges and is in a format +that is executable but not valid for this system (such as a recognized +binary for another architecture), then this is an error and +.IR errno +is set to +.BR [EINVAL] +(see later RATIONALE on +.BR [EINVAL] ). +.IP " 3." 4 +If the process image file has appropriate privileges but is not +otherwise recognized: +.RS 4 +.IP " a." 4 +If this is a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then they invoke a command interpreter assuming that the process image +file is a shell script. +.IP " b." 4 +If this is not a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then an error occurs and +.IR errno +is set to +.BR [ENOEXEC] . +.RE +.P +Applications that do not require to access their arguments may use +the form: +.sp +.RS 4 +.nf + +main(void) +.fi +.P +.RE +as specified in the ISO\ C standard. However, the implementation will always +provide the two arguments +.IR argc +and +.IR argv , +even if they are not used. +.P +Some implementations provide a third argument to +\fImain\fR() +called +.IR envp . +This is defined as a pointer to the environment. The ISO\ C standard +specifies invoking +\fImain\fR() +with two arguments, so implementations must support applications +written this way. Since this volume of POSIX.1\(hy2017 defines the global variable +.IR environ , +which is also provided by historical implementations and can be used +anywhere that +.IR envp +could be used, there is no functional need for the +.IR envp +argument. Applications should use the +\fIgetenv\fR() +function rather than accessing the environment directly via either +.IR envp +or +.IR environ . +Implementations are required to support the two-argument calling +sequence, but this does not prohibit an implementation from supporting +.IR envp +as an optional third argument. +.P +This volume of POSIX.1\(hy2017 specifies that signals set to SIG_IGN +remain set to SIG_IGN, and that the new process image inherits the +signal mask of the thread that called +.IR exec +in the old process image. This is consistent with historical +implementations, and it permits some useful functionality, such as the +.IR nohup +command. However, it should be noted that many existing applications +wrongly assume that they start with certain signals set to the default +action and/or unblocked. In particular, applications written with a +simpler signal model that does not include blocking of signals, such as +the one in the ISO\ C standard, may not behave properly if invoked with some +signals blocked. Therefore, it is best not to block or ignore signals +across +.IR exec s +without explicit reason to do so, and especially not to block signals +across +.IR exec s +of arbitrary (not closely cooperating) programs. +.P +The +.IR exec +functions always save the value of the effective user ID +and effective group ID +of the process at the completion of the +.IR exec , +whether or not the set-user-ID +or the set-group-ID +bit of the process image file is set. +.P +The statement about +.IR argv [\|] +and +.IR envp [\|] +being constants is included to make explicit to future writers of +language bindings that these objects are completely constant. Due to a +limitation of the ISO\ C standard, it is not possible to state that idea in +standard C. Specifying two levels of +.IR const \-\c +.IR qualification +for the +.IR argv [\|] +and +.IR envp [\|] +parameters for the +.IR exec +functions may seem to be the natural choice, given that these functions +do not modify either the array of pointers or the characters to which +the function points, but this would disallow existing correct code. +Instead, only the array of pointers is noted as constant. The table of +assignment compatibility for +.IR dst =\c +.IR src +derived from the ISO\ C standard summarizes the compatibility: +.TS +box tab(!) center; +r | lB | lB | lB | lB +lB | c | c | c | c. +\fIdst\fP:!char *[\|]!const char *[\|]!char *const[\|]!const char *const[\|] +_ +\fIsrc\fP: +char *[\|]!VALID!\(em!VALID!\(em +const char *[\|]!\(em!VALID!\(em!VALID +char * const [\|]!\(em!\(em!VALID!\(em +const char *const[\|]!\(em!\(em!\(em!VALID +.TE +.P +Since all existing code has a source type matching the first row, the +column that gives the most valid combinations is the third column. The +only other possibility is the fourth column, but using it would require +a cast on the +.IR argv +or +.IR envp +arguments. It is unfortunate that the fourth column cannot be used, +because the declaration a non-expert would naturally use would be that +in the second row. +.P +The ISO\ C standard and this volume of POSIX.1\(hy2017 do not conflict on the use of +.IR environ , +but some historical implementations of +.IR environ +may cause a conflict. As long as +.IR environ +is treated in the same way as an entry point (for example, +\fIfork\fR()), +it conforms to both standards. A library can contain +\fIfork\fR(), +but if there is a user-provided +\fIfork\fR(), +that +\fIfork\fR() +is given precedence and no problem ensues. The situation is similar +for +.IR environ : +the definition in this volume of POSIX.1\(hy2017 is to be used if there is no user-provided +.IR environ +to take precedence. At least three implementations are known to exist +that solve this problem. +.TP +.BR E2BIG +The limit +{ARG_MAX} +applies not just to the size of the argument list, but to the sum of +that and the size of the environment list. +.TP +.BR EFAULT +Some historical systems return +.BR [EFAULT] +rather than +.BR [ENOEXEC] +when the new process image file is corrupted. They are non-conforming. +.TP +.BR EINVAL +This error condition was added to POSIX.1\(hy2008 to allow an implementation to +detect executable files generated for different architectures, and +indicate this situation to the application. Historical implementations +of shells, +\fIexecvp\fR(), +and +\fIexeclp\fR() +that encounter an +.BR [ENOEXEC] +error will execute a shell on the assumption that the file is a shell +script. This will not produce the desired effect when the file is a +valid executable for a different architecture. An implementation may +now choose to avoid this problem by returning +.BR [EINVAL] +when a valid executable for a different architecture is encountered. +Some historical implementations return +.BR [EINVAL] +to indicate that the +.IR path +argument contains a character with the high order bit set. The +standard developers chose to deviate from historical practice for the +following reasons: +.RS 12 +.IP " 1." 4 +The new utilization of +.BR [EINVAL] +will provide some measure of utility to the user community. +.IP " 2." 4 +Historical use of +.BR [EINVAL] +is not acceptable in an internationalized operating environment. +.RE +.TP +.BR ENAMETOOLONG +.br +Since the file pathname may be constructed by taking elements in the +.IR PATH +variable and putting them together with the filename, the +.BR [ENAMETOOLONG] +error condition could also be reached this way. +.TP +.BR ETXTBSY +System V returns this error when the executable file is currently open +for writing by some process. This volume of POSIX.1\(hy2017 neither requires nor prohibits this +behavior. +.P +Other systems (such as System V) may return +.BR [EINTR] +from +.IR exec . +This is not addressed by this volume of POSIX.1\(hy2017, but implementations may have a +window between the call to +.IR exec +and the time that a signal could cause one of the +.IR exec +calls to return with +.BR [EINTR] . +.P +An explicit statement regarding the floating-point environment (as +defined in the +.IR <fenv.h> +header) was added to make it clear that the floating-point environment +is set to its default when a call to one of the +.IR exec +functions succeeds. The requirements for inheritance or setting to the +default for other process and thread start-up functions is covered by +more generic statements in their descriptions and can be summarized as +follows: +.IP "\fIposix_spawn\fR\^(\|)" 14 +Set to default. +.IP "\fIfork\fR\^(\|)" 14 +Inherit. +.IP "\fIpthread_create\fR\^(\|)" 14 +Inherit. +.P +The purpose of the +\fIfexecve\fR() +function is to enable executing a file which has been verified to be +the intended file. It is possible to actively check the file by reading +from the file descriptor and be sure that the file is not exchanged for +another between the reading and the execution. Alternatively, a +function like +\fIopenat\fR() +can be used to open a file which has been found by reading the content +of a directory using +\fIreaddir\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIalarm\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fInice\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB<unistd.h>\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fItest\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |