path: root/man-pages-posix-2017/man3p/exec.3p

'\" 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 .