execve(2) DG/UX 4.30 execve(2)
NAME
execve - Execute a program file.
SYNOPSIS
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
Execve 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 execve
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 execve is a null terminated string of
ASCII 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 execve call will fail and an
error will be returned if file access to the program file is
Licensed material--property of copyright holder(s) Page 1
execve(2) DG/UX 4.30 execve(2)
not granted or if its format is invalid.
Execve 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 execve system
call, or pointers to the arguments may be placed in an array
with the array being the argument to the execve system call.
The environment pointer is explicitly given as an argument
to execve.
If execve 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 execve, 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.
If the set-user-id file access mode bit of the file named by
<path> is set, execve 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
Licensed material--property of copyright holder(s) Page 2
execve(2) DG/UX 4.30 execve(2)
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
execve 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
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)
Licensed material--property of copyright holder(s) Page 3
execve(2) DG/UX 4.30 execve(2)
If execve should fail due to any errors, the calling
process's address space is not modified, and the execve 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, argv, 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.
RETURN VALUE
If execve 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
Execve 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.
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.
Licensed material--property of copyright holder(s) Page 4
execve(2) DG/UX 4.30 execve(2)
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).
Licensed material--property of copyright holder(s) Page 5