'\"macro stdmacro
.if n .pH g2.exec @(#)exec	40.34 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} exec 2 "" "\&"
.if \nX=1 .ds x} exec 2 ""
.if \nX=2 .ds x} exec 2 "" "\&"
.if \nX=3 .ds x} exec "" "" "\&"
.TH \*(x}
.SH NAME
\f4exec\f2: \f4execl\f1, \f4execv\f1, \f4execle\f1, \f4execve\f1, \f4execlp\f1, \f4execvp\f1 \- execute a file
.SH SYNOPSIS
.na
\f4#include <unistd.h>
.HP
\f4int execl (const char \(**path, const char \(**arg0, ..., const char \(**argn, (char *)0);\f1
.HP
\f4int execv (const char \(**path, char \(**const \(**argv);\f1
.HP
\f4int execle (const char \(**path, const char \(**arg0, ..., const char \(**argn, (char *0), const char \(**envp[]);\f1
.HP
\f4int execve (const char \(**path, char \(**const \(**argv, char \(**const \(**cnup);\f1
.HP
\f4int execlp (const char \(**file, const char \(**arg0, ..., const char \(**argn, (char *)0);\f1
.HP
\f4int execvp (const char \(**file, char \(**const \(**argv);\f1
.ad
.SH DESCRIPTION
\f4exec\fP
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
\f4exec\fP
because the calling process image is overlaid by the new process image.
.PP
An interpreter file begins with a line of the form
.P
.RS
\f4#! \f2pathname\f1 \f1[\f2arg\f1]
.RE
.P
where \f2pathname\f1 is the path of the interpreter, and
\f2arg\f1 is an optional argument.
When an interpreter file is
exec'd,
the system
execs the specified
interpreter.
The pathname specified in the interpreter file is passed as \f2arg0\f1
to the interpreter.
If \f2arg\f1 was specified in the interpreter file, it is
passed as \f2arg1\f1 to the interpreter.
The remaining arguments to the interpreter are \f2arg0\f1 through \f2argn\f1
of the originally exec'd file.
.PP
When a C program is executed, it is called as follows:
.PP
.RS
\f4int main (int argc, char \(**argv[], char \(**envp[]);\f1
.RE
.PP
where
.I argc
is the argument count,
.I argv
is an array of character pointers to the arguments themselves, and
.I envp
is an array of character pointers to the environment strings.
As indicated,
.I argc
is at least one, and the first member of the array
points to a string containing the name of the file.
.PP
.I path\^
points to a path name that identifies the new process file.
.PP
.I file\^
points to the new process file.
If \f2file\f1 does not contain a slash character,
the path prefix for this file is obtained by a search of the directories
passed in the \f4PATH\f1 environment
variable [see
\f4environ\fP(5)].
The environment
is supplied typically by the shell [see
\f4sh\fP(1)].
.PP
If the new process file is not an executable object file, \f4execlp\fP
and \f4execvp\fP use the contents of that file as standard input to
\f4sh\fP(1).
.PP
The
arguments \f2arg0\f4, \f2...\f4, \f2argn\f1
point to null-terminated character strings.
These strings constitute the argument list available to the new process
image.  Minimally,
.I arg0
must be present.
It will become the name of the process, as displayed by
the \f4ps\fP command.
Conventionally,
.I arg0
points to a string that is the same as
.I path\^
(or the last component of
.IR path ")."
The list of argument strings is
terminated by a \f4(char \(**)0\f1 argument.
.PP
.I argv\^
is an array of character pointers to null-terminated strings.
These strings constitute the argument list available to the new process
image.
By convention,
.I argv\^
must have at least one member, and it should point to a string that is the same as
.IR path\^
(or its last component).
.I argv\^
is terminated by a null pointer.
.PP
.I envp\^
is an array of character pointers to null-terminated strings.
These strings constitute the environment
for the new process image.
.I envp\^
is terminated by a null pointer.
For
\f4execl\fP,
\f4execv\fP,
\f4execvp\fP,
and
\f4execlp\fP,
the C run-time start-off routine places a pointer to the
environment of the calling process in the global object
\f4extern char \(**\(**environ\f1,
and it is used to pass the environment of the calling process to the new process.
.PP
File descriptors open in the calling process remain open in the new process,
except for those whose
\%close-on-exec
flag is set; [see
\f4fcntl\fP(2)].
For those file descriptors that remain open, the file pointer is unchanged.
.PP
Signals that are being caught by the calling process are set to
the default disposition in the new process image [see \f4signal\fP(2)].
Otherwise, the new process image inherits the signal
dispositions of the calling process.
.PP
If the set-user-\s-1ID\s+1
mode bit of the new process file is set
[see
\f4chmod\fP(2)],
\f4exec\fP
sets the effective user
.SM ID
of the new process to the owner
.SM ID
of the new process file.
Similarly, if the set-group-\s-1ID\s+1 mode bit of the
new process file is set, the effective group
.SM ID
of the new process
is set to the group
.SM ID
of the new process file.
The real user
.SM ID
and real group
.SM ID
of the new process remain the same as those of the calling process.
.PP
If the effective user-\s-1ID\s+1 is \f4root\f1 or super-user,
the set-user-\s-1ID\s+1 and set-group-\s-1ID\s+1 bits will be
honored when the process is being controlled by \f4ptrace\fP.
.PP
The shared memory segments attached to the calling process will not be
attached to the new process
[see \f4shmop\fP(2)].
.PP
Profiling is disabled for the new process; see
\f4profil\fP(2).
.PP
The new process also inherits the following attributes from the calling process:
.PP
.PD 0
.RS 0.5i
.PP
nice value [see
\f4nice\fP(2)]
.PP
scheduler class and priority [see
\f4priocntl\fP(2)]
.PP
process
.SM ID
.PP
parent process
.SM ID
.PP
process group
.SM ID
.PP
supplementary group
.SM IDs
.PP
\f4semadj\fP values [see
\f4semop\fP(2)]
.PP
session
.SM ID
[see
\f4exit\fP(2)
and
\f4signal\fP(2)]
.PP
trace flag [see
\f4ptrace\fP(2) request 0]
.PP
time left until an alarm clock signal [see
\f4alarm\fP(2)]
.PP
current working directory
.PP
root directory
.PP
file mode creation mask [see
\f4umask\fP(2)]
.PP
resource limits [see
\f4getrlimit\fP(2)]
.PP
\f4utime\fP,
\f4stime\fP,
\f4cutime\fP,
and
\f4cstime\fP
[see
\f4times\fP(2)]
.PP
file-locks [see \f4fcntl\fP(2) and \f4lockf\fP(3C)]
.PP
controlling terminal
.PP
process signal mask [see \f4sigprocmask\fP(2)]
.PP
pending signals [see \f4sigpending\fP(2)]
.RE
.PD
.PP
Upon successful completion,
\f4exec\f1 marks for update the
\f4st_atime\f1
field of the file.
Should the \f4exec\f1 succeed, the process image file is considered
to have been \f4open()\f1-ed. The corresponding \f4close()\f1 is considered
to occur at a time after this open, but before process termination or successful
completion of a subsequent call to \f4exec\f1.
.PP
\f4exec\fP
will fail and return to the calling process if one or more of the
following are true:
.TP 20
\f4EACCES\fP
Search permission is denied for a directory listed in the new process file's
path prefix.
.TP 20
\f4E2BIG\fP
The number of bytes in the new process's argument list is greater than the
system-imposed limit of 5120 bytes.
The argument list limit is sum of the size of the argument
list plus the size of the environment's exported shell variables.
.TP
\f4EACCES\fP
The new process file is not an ordinary file.
.TP
\f4EACCES\fP
The new process file mode denies execution permission.
.TP
\f4EAGAIN\fP
Total amount of system memory available when
reading via raw I/O is temporarily insufficient.
.TP
\f4EFAULT\fP
Required hardware is not present.
.TP
\f4EFAULT\fP
An \f2a.out\f1 that was compiled with the MAU or 32B flag is
running on a machine without a MAU or 32B.
.TP
\f4EFAULT\fP
An argument
points to an illegal address.
.TP
\f4EINTR\fP
A signal was caught during the \f4exec\fP system call.
.TP
\f4ELIBACC\fP
Required shared library does not have execute permission.
.TP
\f4ELIBEXEC\fP
Trying to \f4exec\fP(2) a shared library directly.
.TP
\f4ELOOP\fP
Too many symbolic links were encountered in translating
\f2path\f1 or \f2file\f1.
.TP
\f4EMULTIHOP\fP
Components of \f2path\f1 require hopping to multiple
remote machines
and the file system type does not allow it.
.TP
\f4ENAMETOOLONG\fP
The length of the \f2file\f1 or \f2path\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2file\f1 or \f2path\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP
\f4ENOENT\fP
One or more components of the new process path name of the file do not exist
or is a null pathname.
.TP
\f4ENOTDIR\fP
A component of the new process path of the file prefix is not a directory.
.TP
\f4ENOEXEC\fP
The
\f4exec\fP
is not an
\f4execlp\fP
or
\f4execvp\fP,
and the new process file has the appropriate access permission
but an invalid magic number in its header.
.TP
\f4ETXTBSY\fP
The new process file is a pure procedure (shared text) file that is
currently open for writing by some process.
.TP
\f4ENOMEM\fP
The new process requires more memory than is allowed by the system-imposed
maximum
.SM MAXMEM.
.TP
\f4ENOLINK\fP
\f2path\f1 points to a remote machine and the link
to that machine is no longer active.
.SH "SEE ALSO"
\f4alarm\fP(2),
\f4exit\fP(2),
\f4fcntl\fP(2),
\f4fork\fP(2),
\f4getrlimit\fP(2),
\f4nice\fP(2),
\f4priocntl\fP(2),
\f4ptrace\fP(2),
\f4semop\fP(2),
\f4signal\fP(2),
\f4sigpending\fP(2),
\f4sigprocmask\fP(2),
\f4times\fP(2),
\f4umask\fP(2),
\f4lockf\fP(3C),
\f4system\fP(3S),
\f4a.out\fP(4),
\f4environ\fP(5).
.br
\f4sh\fP(1), \f4ps\fP(1) in the
\f2User's Reference Manual\f1.
.SH DIAGNOSTICS
If
\f4exec\fP
returns to the calling process, an error has occurred; the return value
is \-1 and
\f4errno\fP
is set to indicate the error.
