 |
Index for
Section 2 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
exec(2)
NAME
environ, execl, execv, execle, execve, execlp, execvp - Executes a file
LIBRARY
Standard C Library (libc.a, libc.so)
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[ ] );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
execl(), execv(), execv(), execle(), execve(), execlp(), execvp(): POSIX.1,
XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
path Points to a pathname identifying the new process image file.
arg... 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 filename 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.
argv 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 filename
of the process being started by execv(), execve(), or execvp().
The last member of this array must be a null pointer.
envp 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.
file 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.
Otherwise, the system searches the directories specified in the
PATH environment 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 the 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 filename 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 corresponding 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 environment 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 executable 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
interpreter_name string. When executing an executable text file, the
system modifies the arguments passed to the exec function being used as
follows:
· argv[0] is set to the name of the interpreter. For example, the ksh
shell might be the interpreter.
· If the optional_string is present, argv[1] is set to the
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 original 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 execlp()
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.
File descriptors open in the calling process image remain open in the new
process image, except for those whose close-on-exec flag, FD_CLOEXEC, is
set (see fcntl(2) for more information). For those file descriptors that
remain open, all attributes of the open file description, including file
locks, remain unchanged.
Directory streams 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() function
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 calling 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 flag 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.
Any mappings established through mmap() are not preserved across an exec.
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
· Supplementary group IDs
· Time left until an alarm clock signal (see alarm(3) for more
information)
· Current working directory
· Root directory
· File mode creation mask (see umask(2) for more information)
· Process signal mask (see sigprocmask(2) for more information)
· Pending signals (see sigpending(2) for more information)
· The tms_utime, tms_stime, tms_cutime, and tms_cstime fields of the tms
structure
· File size limit (see the ulimit() function)
· Nice value (see nice(3) for more information)
· Adjust-on-exit values (see semop(2) for more information)
· Resource limits
· Controlling terminal
· Interval timers
Upon successful completion, the exec functions mark for update the st_atime
field of the file.
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:
[E2BIG] The number of bytes used by the new process image's argument list
and environment list is greater than ARG_MAX bytes.
[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, or the new process image file is not
an executable file type.
[EACCES] [Tru64 UNIX] The security attributes of the program file do not
allow execute permission.
[EAGAIN] [Tru64 UNIX] The calling process is using a kernel 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.
[EFAULT] [Tru64 UNIX] The path argument is an invalid address.
[EIO] [Tru64 UNIX] An I/O error occurred.
[ELOOP] Too many symbolic links were encountered in pathname resolution.
[ENAMETOOLONG]
One of the following 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.
[ENOENT] 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.
[ENOMEM] Insufficient memory is available.
[ENOTDIR] 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:
[ENOEXEC] 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:
[EWOULDBLOCK]
[Tru64 UNIX] Indicates that another thread in the process is
already performing an execlp() or execvp() operation.
RELATED INFORMATION
Functions: exit(2), fcntl(2), fork(2), sigaction(2), umask(2), mmap(2),
exec_with_loader(2)
Routines: alarm(3), getenv(3), nice(3), putenv(3), system(3), times(3),
ulimit(3)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|