exec(2)exec(2)NAME
environ, execl, execv, execle, execve, execlp, execvp - Execute a file
SYNOPSIS
#include <unistd.h>
extern char **environ;
int execl(
const char *path,
const char *arg,
... ); int execv(
const char *path,
char * const argv[] ); int execle(
const char *path,
const char *arg,
...,
char * const envp[] ); int execve(
const char *path,
char * const argv[],
char * const envp[] ); int execlp(
const char *file,
const char *arg,
... ); int execvp(
const char *file,
char * const argv[] );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
execl(), execle(), execlp(),execv(), execve(), execvp(): POSIX.1,
XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Points to a pathname identifying the new process image file. Specifies
a pointer to a null-terminated string, which is one argument available
to the new process image. The first of these parameters points to the
file name that is associated with the process being started by execl(),
execle(), or execlp(). The last element in the list of arg parameters
must be a null pointer. Specifies an array of character pointers to
null-terminated strings, which are the arguments available to the new
process image. The value in the argv[0] parameter points to the file
name of the process being started by execv(), execve(), or execvp().
The last member of this array must be a null pointer. Specifies an
array of character pointers to null-terminated strings, constituting
the environment for the new process. This array must be terminated by a
null pointer. Identifies the new process image file. If this parameter
points to a string containing a slash character, its contents are used
as the absolute or relative pathname to the process image file. Other‐
wise, the system searches the directories specified in the PATH envi‐
ronment variable definition associated with the new process image to
obtain a path prefix for the file.
DESCRIPTION
The exec functions replace the current process image with a new process
image. The system constructs the new image from an executable file,
called a new process image file. Successful calls to exec functions do
not return because the system overlays the calling process with the new
process.
To run an executable file using one of the exec functions, applications
include a function call such as the following:
int main (
int argc,
char *argv[ ] );
Here, the argc parameter contains the number of arguments being passed
to the new main function. The argv[ ] parameter is a null-terminated
array of character pointers that point to the arguments themselves.
(The null pointer is not included in the count specified in the argc
parameter.) The value in argv[0] should point to the file name that is
associated with the process being started by one of the exec functions.
The system passes the arguments to the new process image in the corre‐
sponding arguments to main().
For forms of the exec functions that do not include the envp parameter,
applications also define the environ variable to be a pointer to an
array of character strings. The character strings define the environ‐
ment in which the new process image runs. For example, the following
shows how an application defines the environment variable:
extern char **environ;
The environ array is terminated by a null pointer.
The format of the new process image file must be one that is recognized
by the exec function being used. The exec functions recognize exe‐
cutable text files and binary files.
An executable text file is one that contains a header line with the
following syntax:
#! interpreter_name [ optional_string ]
The #! identifies the file as an executable text file. The new process
image is constructed from the process image file named by the inter‐
preter_name string. When executing an executable text file, the system
modifies the arguments passed to the exec function being used as fol‐
lows: argv[0] is set to the name of the interpreter. For example, the
ksh shell might be the interpreter. If optional_string is present,
argv[1] is set to optional_string. The next element of argv[] is set
to the original value of path. The remaining elements of argv[] are
set to the original elements of argv[], starting at argv[1]. The origi‐
nal argv[0] is discarded.
A binary file can be loaded either directly by an exec function or
indirectly by the program loader. The exec functions choose to use
direct or indirect loading based on the contents of the new process
image file. For example, the functions use indirect loading if the new
process image file contains unresolved symbols, requiring use of a
shared library.
When an exec function loads a binary file indirectly, it constructs the
new process image from the default program loader, /sbin/loader, in the
same manner as the exec_with_loader() function (see
exec_with_loader(2)). The default program loader is then responsible
for completing the new program image by loading the new process image
file and any shared libraries on which it depends.
If the process image file is not a valid executable object, the exe‐
clp() and execvp() functions use the contents of that file as standard
input to a command interpreter conforming to the system() function. In
this case, the command interpreter becomes the new process image.
The number of bytes available for the combined argument and environment
lists of the new process image is ARG_MAX. ARG_MAX includes the null
terminators on the strings; it does not include the pointers.
[Tru64 UNIX] The exec_disable_arg_limit attribute of the proc kernel
subsystem can be set to disable hard limits on the number of arguments
that a command can have when it executes. By default, hard limits are
enforced. For more information about disabling hard limits, see
sys_attrs_proc(5).
File descriptors open in the calling process image remain open in the
new process image, except for those whose close-on-exec option,
FD_CLOEXEC, is set (see fcntl(2) for more information). For those file
descriptors that remain open, all attributes of the open file descrip‐
tion, including file locks, remain unchanged.
Directory streams that are open in the calling process image are closed
in the new process image.
The state of directory streams and message catalog descriptors in the
new process image is undefined. For the new process, the equivalent of
the following command is executed at startup:
setlocale(LC_ALL, "C")
Each mapped file and shared memory region created with the mmap() func‐
tion is unmapped by a successful call to any of the exec functions,
except those regions mapped with the MAP_INHERIT option. Regions mapped
with the MAP_INHERIT option remain mapped in the new process image.
Signals set to the default action (SIG_DFL) in the calling process
image are set to the default action in the new process image. Signals
set to be ignored (SIG_IGN) by the calling process image are set to be
ignored by the new process image. Signals set to be caught by the call‐
ing process image are set to the default action in the new process
image.
After a successful call to any of the exec functions, alternate signal
stacks are not preserved and the SA_ONSTACK option is cleared for all
signals.
After a successful call to any of the exec functions, any functions
previously registered by atexit() are no longer registered.
If the ST_NOSUID bit is set for the file system containing the new
process image file, the effective user ID, effective group ID, saved
set user ID, and saved set group ID are unchanged in the new process.
Otherwise, if the set user ID mode bit of the new process image file is
set (see chmod(2) for more information), the effective user ID of the
new process image is set to the owner 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 is 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 remain the
same as those of the calling process image. The effective user ID and
effective group ID of the new process image are saved (as the saved set
user ID and the saved set group ID) for use by the setuid() function.
Any shared memory segments attached to the calling process image are
not attached to the new process image.
The following attributes of the calling process image are unchanged
after successful completion of any of the exec functions. For example,
a new process inherits these attributes: Process ID Parent process ID
Process group ID Session membership Real user ID Real group ID Supple‐
mentary group IDs Time left until an alarm clock signal. See alarm(3).
Current working directory Root directory File mode creation mask. See
umask(2). Process signal mask. See sigprocmask(2). Pending signals.
See sigpending(2). The tms_utime, tms_stime, tms_cutime, and
tms_cstime fields of the tms structure File size limit. See ulimit(3).
Nice value. See nice(3). Adjust-on-exit values. See semop(2).
Resource limits Controlling terminal Interval timers
Upon successful completion, the exec functions mark for update the
st_atime field of the file.
A call to an exec function does not change the SCHED_FIFO, SCHED_RR, or
SCHED_OTHER scheduling policies. (SCHED_OTHER is the same as the Tru64
UNIX timeshare scheduling policy.) However, libraries, such as the
POSIX threads library, also implement scheduling policies, so support
for different scheduling policies is not limited to the kernel sched‐
uler.
On a successful call to one of the exec functions, memory locks that
were established by the calling process through calls to mlockall() or
mlock are 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 pro‐
cesses are not not affected by the call to the exec function.
Memory mappings created in the process are unmapped before the address
space is rebuilt for the new process image.
Per process timers created by the calling process are deleted before
replacing the current process image with the new process image.
Any outstanding asynchronous I/O operations are canceled before the new
image overwrites the calling process image.
POSIX semaphores and message queue descriptors are not stored in the
kernel and therefore are not explicitly closed; However, they are auto‐
matically deleted when the new image overwrites the calling process
image.
NOTES
If a multithreaded process calls one of the exec functions, all threads
except the calling thread are terminated, and the calling thread begins
execution within the new process image.
RETURN VALUES
If one of the exec functions returns to the calling process image, an
error has occurred; the return value is -1, and the function sets errno
to indicate the error.
ERRORS
The exec functions set errno to the specified values for the following
conditions: The number of bytes used by the new process image's argu‐
ment list and environment list is greater than ARG_MAX bytes. 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 per‐
mission, or the new process image file is not an executable file type.
[Tru64 UNIX] The security attributes of the program file do not allow
execute permission. [Tru64 UNIX] The calling process is using a ker‐
nel subsystem that prevents executing the new image. The call to one of
the exec functions will not succeed until the process has detached
itself from the subsystem. [Tru64 UNIX] The path argument is an
invalid address. [Tru64 UNIX] An I/O error occurred. Too many sym‐
bolic links were encountered in pathname resolution. One of the fol‐
lowing conditions occurred: The length of the path argument, the file
argument, or an element of the environment variable PATH prefixed to a
file exceeds PATH_MAX. A pathname component is longer than NAME_MAX,
and _POSIX_NO_TRUNC is in effect for that file. One or more components
of the new process image file's pathname do not exist, or the path or
file argument points to an empty string. Insufficient memory is avail‐
able. A component of the new process image file's path prefix is not a
directory.
The execl(), execv(), execle(), and execve() functions also set errno
as follows:
The new process image file has the appropriate access permission but is
not in the proper format.
The execlp() and execvp() functions also set errno as follows:
[Tru64 UNIX] Another thread in the process is already performing an
execlp() or execvp() operation.
SEE ALSO
Functions: exit(2), fcntl(2), fork(2), sigaction(2), umask(2), mmap(2),
exec_with_loader(2)
Routines: alarm(3), getenv(3), nice(3), getluid(3), setluid(3),
putenv(3), system(3), times(3), ulimit(3)
Others: standards(5)exec(2)
