execve(2)
_________________________________________________________________
execve System Call
Execute a program file.
_________________________________________________________________
SYNTAX
None.
int execve (path, argv, envp)
char * path;
char ** argv;
char ** envp;
PARAMETERS
path The pathname of the program file to be executed.
argv An array of pointers to the null-terminated byte
strings that are to be the arguments passed to the
new program. The last entry in the array must be
a null pointer.
envp An array of pointers to the null-terminated byte
strings that are to constitute the environment of
the new program. The last entry in the array must
be a null pointer.
DESCRIPTION
Exec in all its forms (see execle, execv, and execl) replaces the
address space of the calling process with a new address space
initialized from an ordinary executable file, called the new
program file. The exec call does not return if it is successful;
after the process's address space has been reinitialized, user
execution begins at the starting address specified in the new
program file. Information may be passed from the old address
space to the new address space in the form of arguments and an
environment. (While the arguments and environment are
uninterpreted by the kernel, the arguments are typically program
specific values while the environment is more general information
such as the default search directories. The kernel simply
provides a mechanism that can be used as desired by the shell or
any other program.)
The <path> argument to exec is a null terminated string of ASCII
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
execve(2)
characters that directly specifies the new program file or
specifies an interpreter file. An interpreter file has the
ASCII characters #! as the first two bytes, followed by zero or
more tabs or blanks, followed by the interpreter pathname, which
must be a program file. The interpreter pathname may optionally
be followed by one or more tabs or blanks, and a newline-
terminated character string. This character string will be
supplied as an argument to the interpreter; see below. The exec
call will fail and an error will be returned if file access to
the program file is not granted or if its format is invalid.
Exec provides for the new program to be given a set of arguments
and an environment, each of which may be supplied in one of two
ways. Each argument for the new program may be explicitly listed
as an argument to the exec system call, or pointers to the
arguments may be placed in an array with the array being the
argument to the exec system call. The environment pointer may be
explicitly given as an argument to exec, or exec will use the
default "environment" pointer value stored at a fixed location in
the calling process's user address space. The cross-product of
the two options results in four callable interfaces to exec, the
choice of which depends upon how the arguments and environment
are supplied.
If exec determines that path points to an interpreter file rather
than a program file, the arguments that are passed to the program
specified by the interpreter pathname are modified. The
interpreter pathname is inserted as argument 0, and if present
its optional argument is inserted as argument 1. All of the
original arguments are shifted right one, or two positions, if
the interpreter optional argument is not present; i.e., argument
0 becomes argument 1, argument 1 becomes argument 2, etc.
In the new address space, execution begins at the starting
address specified in the new program file with the argument
count, a pointer to an array of argument pointers, and the
environment pointer. (The runtime environment in the new address
space is responsible for making the arguments and environment
available to the application program in the familiar "main(argc,
argv, envp)" format.)
All object descriptors open in the calling process remain open
after the exec, except for those whose close-on-exec flag is set.
For object descriptors that remain open the object pointer is
unchanged. All other object descriptors are closed.
The software signal structures are modified in the following
manner: 1) The signal action vector with components set to
`catch' are changed to `default'. 2) The signal stack context is
discarded. 3) All other software signal structures are
unchanged.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
execve(2)
If the set-user-id file access mode bit of the file named by
<path> is set, exec sets the effective-user-id of the calling
process to the user-id of that file. Similarly, if the set-
group-id file access mode bit of the file named by <path> is set,
the effective-group-id of the calling process is set to the
group-id of that file. The real-user-id and real-group-id of the
calling process remain unchanged. Note that if the file named by
<path> is an interpreter file, the set-user-id and set-group-id
bits of the interpreter file are examined while the corresponding
bits of the new program file are ignored. The set-user-id and
set-group-id bits are ignored and the effective-user-id and
effective-group-id of the process are not changed if the process
is being traced (i.e., it executed the ptrace() system call with
option 0).
If the calling process is a child created by vfork, all shared
memory segments are returned to its parent. Otherwise, all
shared memory segments attached to the calling process will be
detached before the new address space is created. The shared
memory segments will not be reattached to the new address space.
The user-specified paging behavior (see vadvise) is set to its
default value, and any text or data segment locks (see plock) are
released. If the calling process is a child created by vfork,
the text and data segment locks are returned to its parent along
with the rest of the address space.
Profiling is disabled for the new process; see profil.
If the process is being traced, it is sent a SIGTRAP signal after
all other effects of this call have completed, but before the
first instruction in the new address space is executed.
The following attributes have the same value after the exec call
as they did before:
nice value (see nice)
process ID
parent process ID
process group ID
real-user-id, real-group-id, and group list
tty_group_id
semaphore adjustment values (see semop)
trace flag (see ptrace request 0)
time left until an alarm clock signal (see alarm)
time left until an interval timer signal
current working directory
root directory
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
execve(2)
file mode creation mask (see umask)
resource utilization limits (see ulimit, setrlimit)
current resources consumed (see getrusage)
cumulative resources consumed by children
pending signal vector
blocked signal vector
controlling terminal device
file locks (unless the descriptor is close-on-exec)
If exec should fail due to any errors, the calling process's
address space is not modified, and the exec call returns.
ACCESS CONTROL
The calling process must have standard execute access to the new
program file to be executed, and at least one of the execute
permission bits for owner, group, or other must be set. (The
distinction is that the superuser will have standard execute
access even if none of the execute permission bits are set. This
call requires that at least one of those bits be set, even for
the superuser.) If the <path> argument names an interpreter file,
the calling process must also have the above described access to
the interpreter file. The access checks are performed before any
changes are made to the process's effective-user-id and
effective-group-id.
The path, arg<x>, and envp pointers, as well as the pointers in
the argv array must point to valid and readable portions of the
calling process's address space. For execv and execl, the
default "environment" pointer must meet the same requirements.
RETURN VALUE
If exec returns to the calling process an error has occurred; the
return value will be -1 and errno will be set to indicate the
error.
EXCEPTIONS
Exec will fail and return to the calling process if one or more
of the following are true:
ENOENT One or more components of the <path> argument do
not exist.
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
execve(2)
ENOTDIR A non-terminal component of the <path> argument is
not a directory.
EACCES Search permission is denied for a directory listed
in the "path" argument.
EACCES The new program file is not an ordinary file.
EACCES The new program file mode denies execution
permission.
ENOEXEC The new program file has an invalid format.
ETXTBSY The new program file is a pure procedure (shared
text) file that is currently open for writing by
some process.
ENOMEM The new program's address space is larger than the
system-imposed maximum MAXMEM.
E2BIG The number of bytes in the new program's argument
list is greater than the system- imposed limit,
ARGLIMIT.
EFAULT Path, argv, or envp point to an illegal address.
EAGAIN Not enough memory.
SEE ALSO
The related system calls: alarm, exit, fork, nice, ptrace,
semop, signal, times, ulimit, umask.
The related manual sections: sh(1), a.out(4), environ(5).
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)