exec.3p (38439B)
- '\" 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 .