 |
Index for
Section 2 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
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 standards
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
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 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.
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 file name 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 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 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 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 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.
[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 description, 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() 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 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
· Supplementary 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 scheduler.
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 processes 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 automatically
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:
[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] 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)
|
Index for
Section 2 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|