exec(2) exec(2)
NAME
exec: execl, execv, execle, execve, execlp, execvp - execute a
file
SYNOPSIS
#include <unistd.h>
int execl (const char *path, const char *arg0, .../*,
const char *argn, (char *)0*/);
int execv (const char *path, char *const *argv);
int execle (const char *path, const char *arg0, .../*,
const char *argn, (char *)0, const char *envp[]*/);
int execve (const char *path, char *const *argv,
char *const *envp);
int execlp (const char *file, const char *arg0, .../*,
const char *argn, (char *)0)*/;
int execvp (const char *file, char *const *argv);
DESCRIPTION
exec in all its forms overlays a new process image on an old
process. The new process image is constructed from an
ordinary executable file. This file is either an executable
object file or a file of data for an interpreter. There can
be no return from a successful exec because the calling
process image is overlaid by the new process image.
An interpreter file begins with a line of the form
#! pathname [arg]
where pathname is the path of the interpreter, and arg is an
optional argument. When you exec an interpreter file, the
system execs the specified interpreter. The pathname
specified in the interpreter file is passed as arg0 to the
interpreter. If arg was specified in the interpreter file, it
is passed as arg1 to the interpreter. The remaining arguments
to the interpreter are arg0 through argn of the originally
executed file.
When a C program is executed, it is called as follows:
int main (int argc, char *argv[], char *envp[]);
where argc is the argument count, argv is an array of
character pointers to the arguments themselves, and envp is an
array of character pointers to null-terminated strings that
constitute the environment for the new process. The value of
Copyright 1994 Novell, Inc. Page 1
exec(2) exec(2)
the argument argc is conventionally at least one. The initial
member of the array argv points to a string containing the
name of the file.
The argument path points to a pathname that identifies the new
process file. For execlp and execvp, the argument file points
to the new process file. If the file argument does not
contain a slash character, the path prefix for this file is
obtained by searching the directories passed as the
environment variable PATH [see environ(5)]. The environment
is supplied typically by the shell [see sh(1)].
If the new executable file is not an executable object file,
execlp and execvp use the contents of that file as standard
input to sh(1).
The arguments arg0, ... are pointers to null-terminated
character strings. These strings constitute the argument list
available to the new process. The list is terminated by a
null pointer. By convention, at least arg0 is present and
points to a string that is the same as file or path (or its
last component), point to null-terminated character strings.
It will become the name of the process, as displayed by the ps
command. The list of argument strings is terminated by a
(char *)0 argument.
argv is an array of character pointers to null-terminated
strings. These strings constitute the argument list available
to the new process. By convention, argv[0] must have at least
one member, and it should point to a string that is the same
as file or path (or its last component). argv is terminated
by a null pointer.
The argument envp is an array of character pointers to null-
terminated strings. These strings constitute the environment
for the new process. A null pointer terminates envp. For
execl, execv, execvp, and execlp, the C run-time start-off
routine places a pointer to the environment of the calling
process in the global object extern char **environ, and it is
used to pass the environment of the calling process to the new
process image.
File descriptors open in the calling process remain open in
the new process image, except for those whose close-on-exec
flag is set [see fcntl(2)]. For those file descriptors that
remain open, the file pointer remains unchanged and all file
Copyright 1994 Novell, Inc. Page 2
exec(2) exec(2)
locks associated with the file are preserved.
Signals being caught by the calling process are set to the
default disposition in the new process image [see signal(2)].
Otherwise, the new process image inherits the signal
dispositions of the calling process.
If the set-user-ID-on-execution mode bit of the new process
file is set, the exec routines set the effective user ID of
the new process to the owner ID of the new process file [see
chmod(2)]. Similarly, if the set-group-ID mode bit of the new
process file is set, the effective group ID of the new process
is set to the group ID of the new process file. The real user
ID, real group ID and supplementary group IDs of the new
process remain the same as those of the calling process. The
saved user and group IDs of the new process image are set to
the effective user and group IDs of the calling process.
Set-user-ID and set-group-ID on execution may not occur for
interpreter files.
If the effective user-ID is 0, the set-user-ID and set-group-
ID bits are honored when the process is being controlled by
ptrace.
The shared memory segments attached to the calling process
will not be attached to the new process image [see shmop(2)].
Profiling is disabled for the new process image [see
profil(2)].
The new process image also preserves the following attributes
across this system call.
nice value
[see nice(2)] scheduler class and priority [see
priocntl(2)]
process ID
parent process ID
process group ID
supplementary group ID
semadj values
[see semop(2)]
session ID
[see exit(2) and signal(2)]
trace flag
[see ptrace(2) request 0]
Copyright 1994 Novell, Inc. Page 3
exec(2) exec(2)
time left until an alarm clock signal
[see alarm(2)]
current directory
root directory
file mode creation mask
[see umask(2)]
resource limits
[see getrlimit(2)]
utime, stime, cutime, and cstime
[see times(2)]
file-locks
[see fcntl(2) and lockf(3C)]
controlling terminal
process signal mask
[see sigprocmask(2)]
pending signals
[see sigpending(2)]
If exec succeeds, it marks for update the st_atime field of
the file.
If exec succeeds, an internal reference to the process image
file is created. This reference is removed some time later,
but not later than process termination or successful
completion of a subsequent call to one of the exec functions.
Return Values
On success, exec overlays the calling process image with the
new process image and there is no return to the calling
process. If exec fails while it can still return to the
calling process, it returns -1 and sets errno to identify the
error. If exec fails after a point of no return to the
calling process, the calling process is sent a SIGKILL signal.
Errors
If exec returns to the calling LWP, an error has occurred. In
this event, no side effect is suffered. That is, neither the
calling LWP nor the other LWPs in the process are terminated.
In the following conditions, exec fails and sets errno to:
EACCES Search permission is denied for a
directory listed in the new executable
file's path prefix.
Copyright 1994 Novell, Inc. Page 4
exec(2) exec(2)
EACCES The new executable file is not an ordinary
file.
EACCES Execute permission on the new executable
file is denied.
E2BIG The number of bytes in the argument list
of the new process image is greater than
the system-imposed limit of {ARG_MAX}
bytes. The argument list limit is sum of
the size of the argument list plus the
size of the environment's exported shell
variables.
EAGAIN Total amount of system memory available
when reading via raw I/O is temporarily
insufficient.
EFAULT Required hardware is not present.
EFAULT An argument points to an illegal address.
EINTR A signal was caught during the exec system
call.
ELIBACC A required shared library does not have
execute permission.
ELIBEXEC Trying to exec a shared library directly.
ELOOP Too many symbolic links were encountered
in translating path or file.
EMULTIHOP Components of path require hopping to
multiple remote machines and the file
system type does not allow it.
ENAMETOOLONG The length of the file or path argument
exceeds {PATH_MAX}, or the length of a
file or path component exceeds {NAME_MAX}
while _POSIX_NO_TRUNC is in effect.
ENOENT One or more components of the pathname of
the executable file do not exist, or path
or file points to an empty string.
Copyright 1994 Novell, Inc. Page 5
exec(2) exec(2)
ENOLOAD Failure in loading a loadable exec module.
ENOTDIR A component of the pathname of the
executable file is not a directory.
ENOEXEC The exec is not an execlp or execvp, and
the new executable file has the
appropriate access permission but an
invalid magic number in its header.
ENOMEM The new process image requires more memory
than allowed by RLIMIT_VMEM [see
getrlimit(2).
ENOLINK path points to a remote machine and the
link to that machine is no longer active.
REFERENCES
a.out(4), alarm(2), environ(5), exit(2), fcntl(2), fork(2),
getrlimit(2), lockf(3C), nice(2), priocntl(2), ps(1),
ptrace(2), semop(2), sh(1), signal(2), sigpending(2),
sigprocmask(2), system(3S), times(2), umask(2)
NOTICES
Considerations for Threads Programming
A successful exec will effectively terminate all but one
thread of a multithreaded process. The process starts the new
program with a single multiplexed (that is, not bound) thread.
In the case of failure and return of an error condition to the
calling thread, sibling threads are not affected.
Considerations for Lightweight Processes
The process starts the new program with a single LWP. In
general, the LWPID number of that single LWP need not be that
of the LWP of the calling thread; however, if the process is
being accessed via /proc (that is, being debugged) the LWPID
is preserved across the exec system call.
Copyright 1994 Novell, Inc. Page 6