'\"macro stdmacro
.if n .pH g2.exec @(#)exec	41.8 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 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>\fP
.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 \(**envp);\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.
This line may be up to 256 characters long.
\f2arg\f1 includes all characters from the first non-space character after 
\f2pathname\f1 up to, but not including, the newline.
Any tabs in \f2arg\f1 are converted to spaces.
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 \f2argc\fP, char \(**\f2argv\fP[], char \(**\f2envp\fP[]);\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\^,
which is only used with \f4execlp\fP and \f4execvp\fP,
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).  However, if the new process file is setuid or setgid,
the input is passed via \f2/dev/fd/N\f1 (see below for details).
.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.
Unless compilation is done in a pure ANSI environment
(see
\f4cc\fP(1)),
the global variable 
.B _environ
is aliased to the well-known (but non-ANSI-compliant) name
.BR environ .
.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
For signals set by \f4sigset\fP(2), \f4sigaction\fP(2), 
or \f4sigvec\fP(3B), \f4exec\fP will ensure that the
new process has the same system signal action for each signal type
whose action is SIG_DFL, SIG_IGN, or SIG_HOLD as the calling process.
However, if the 
action is to catch the signal, then the action will be reset to 
.\" this just isn't true about 'holding'  pending signals
.\"SIG_DFL, and any pending signal for this type will be held.  All signal
.\"masks associated with handlers are cleared.
SIG_DFL.  All signal
masks associated with handlers are cleared.
.PP
If the file resides on a file system which has been mounted with the
.I nosuid
option [see \f4fstab\fP(4)] then the effective user ID, the effective group
ID and the current capability set [see \f4capabilities\fP(4)] will remain
unchanged.  Otherwise, if the set-user-\s-1ID\s+1 (\s-1SUID\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
(\s-1SGID\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.  And finally, if attributes for the file are
accessible [see \f4attr_get\fP(2)] and the \f4SGI_CAP_FILE\fP attribute is
attached to the file (\s-1SCAP\s+1), then this is used to change the process'
capabilities (see \f4capabilities\fP(4)).
.P
The real user
.SM ID,
real group
.SM ID,
and supplementary group
.SM IDs
of the new process remain the same as those of the calling process.
.P
The saved user and group IDs of the new process are set to the
effective user and group IDs of the calling process.
.PP
If the effective user-\s-1ID\s+1 is \f40\f1, the set-user-\s-1ID\s+1
(\s-1SUID\s+1) and set-group-\s-1ID\s+1 (\s-1SGID\s+1) file mode bits and
any capabilities attached to the file (\s-1SCAP\s+1) will be honored when the
process is being controlled by \f4ptrace\fP.
.PP
When an image with set-user-\s-1ID\s+1 (\s-1SUID\s+1), set-group-\s-1ID\s+2
(\s-1SGID\s+1) or attached capabilities (\s-1SCAP\s+1) is executed it is
dangerous from a security standpoint to respect certain environment
variables which may allow arbitrary code to be linked into the new process
image.  Examples include \f4rld\fP's \s-1\f4_RLD*_LIST\fP\s+1 and
\s-1\f4LD_LIBRARY*_PATH\fP\s+1 environment variables and the Image Format
Library's \s-1\f4IFL_DATABASE\fP\s+1 environment variable (see \f4rld\fP(1)
and \f4ifl\fP(1)).  As a result, these environment variables are ignored
when such an image is executed.  The semantics for determining when it is
dangerous to respect such environment variables are: the real and effective
user \s-1ID\s+1s are different, or the real and effective group \s-1ID\s+1s
are different or if a process has \f2any\fP effective or permitted
capabilities.
.PP
Allowing such environment variables to be used in these circumstances is
dangerous because an unprivileged user may execute an image which has
privileges associated with it.  Allowing the user to specify arbitrary code
to be linked into the new privileged process image would give the user the
ability to circumvent the security policies instituted by the system
administrator.  For instance, if an arbitrary dynamic linked object
(\s-1DSO\s+1) were linked in which provided a resolution for the symbol
\f4strcpy\fP, the priviledge process could call the \f4strcpy\fP() function
thinking that it was making a ``safe'' call to a standard library routine.
.PP
Because of the above security restrictions, a dynamic executable with
attached permissions (\s-1SUID\s+1, \s-1SGID\s+1, and/or \s-1SCAP\s+1) will
not be able to use the \s-1\f4LD_LIBRARY*_PATH\fP\s+1 environment variables
to find dynamic shared objects (\s-1DSO\s+1's) in non-standard library
locations.  Instead, the executable must either explicitly specify the
locations of the \s-1DSO\s+1's it wants to load in its \f4dlopen\fP(3) calls
or must have an \f4rpath\fP embedded within it which specifies the non-standard
library locations that need to be searched for its \s-1DSO\s+1's (see the
documentation for the \f4\-rpath\fP option in \f4ld\fP(1)).
.PP
Set-user-\s-1ID\s+1 (\s-1SUID\s+1), set-group-\s-1ID\s+1 (\s-1SGID\s-1)
interpreter files and those with attached capabilities (\s-1SCAP\s+1) are
handled in a special manner.  If execution of an interpreter file will
change either the user orgroup ID or the file has attached capabilities,
IRIX will open the interpreter file for reading (subject to the read
permissions of the interpreter file and the user and group \s-1ID\s+1 of the
new process).  A pathname corresponding to the interpreter file descriptor
will be substituted for the pathname of the interpreter file in the argument
list passed to the intepreter.  This pathname will be of the form
\f2/dev/fd/\s-1N\s+1\f1 where \f2\s-1N\s+1\f1 is the number of the
interpreter file descriptor.
.PP
The shared memory segments attached to the calling process will not be
attached to the new process
[see \f4shmop\fP(2)].
.PP
If the process is a member of a share group, it is removed from that
share group [see
\f4sproc\fP(2)].
.PP
Profiling is disabled for the new process; see
\f4profil\fP(2).
.PP
Ability to access graphics is disabled.
.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
process
.SM ID
.PP
parent process
.SM ID
.PP
process group
.SM ID
.PP
real user and group
.SM IDs
.PP
supplementary groups
.SM IDs
[see
\f4getgroups\fP(2)]
.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
interval timers [see
\f4getitimer\fP(2)]
.PP
current working directory
.PP
root directory
.PP
file mode creation mask [see
\f4umask\fP(2)]
.PP
file size limit [see 
\f4ulimit\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 14
\f4EACCES\fP
Search permission is denied for a directory listed in the new process file's
path prefix.
.TP
\f4EACCES\fP
The new process file is not an ordinary file.
.TP
\f4EACCES\fP
Execute permission on the new process file is denied.
.TP
\f4E2BIG\fP
The number of bytes in the new process's argument list is greater than the
system-imposed limit
.I {ARG_MAX}
[see
\f4sysconf\fP(2),
\f4intro\fP(2),
and
\f4limits.h\fP].
The argument list limit is the sum of the size of the argument
list plus the size of the environment's exported shell variables.
.TP
\f4E2BIG\fP
The number of bytes in the first line of an interpreter file is greater
than 256 bytes.
.TP
\f4EAGAIN\fP
Not enough memory.
.TP
\f4EFAULT\fP
An argument
points to an illegal address.
.TP
\f4ELIBACC\fP
Required shared library does not have execute permission.
.TP
\f4ELIBEXEC\fP
Trying to \f4exec\fP(2) a shared library directly.
.TP
\f4ELIBMAX\fP
The required number of shared libraries exceeds the system imposed
maximum
.SM
.I {SHLIB_MAX}
[see
\f4intro\fP(2)].
.TP
\f4ELOOP\fP
Too many symbolic links were encountered in translating
\f2path\f1 or \f2file\f1.
.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
\f4ENOEXEC\fP
The executable object file has badly formed header information.
.TP
\f4ENOEXEC\fP
The requested virtual addresses are not available.
.TP
\f4ENOMEM\fP
The new process requires more virtual space than is allowed either by the system-imposed
maximum or the process imposed maximum 
.I {PROCSIZE_MAX}
[see
\f4getrlimit\fP(2)
and
\f4intro\fP(2)].
.TP
\f4EPERM\fP
A non-superuser attempts to execute a setuid or setgid shell script
with a uid or gid which is different than the user's effective
uid/gid, and the configured value for 
.I nosuidshells
is non-zero (the default) [see 
\f4intro\fP(2)
and 
\f4lboot\fP(1M)].
.SH "SEE ALSO"
\f4ps\fP(1),
\f4sh\fP(1), 
\f4lboot\fP(1M),
\f4intro\fP(2),
\f4alarm\fP(2),
\f4exit\fP(2),
\f4fcntl\fP(2),
\f4fork\fP(2),
\f4getgroups\fP(2),
\f4getrlimit\fP(2),
\f4nice\fP(2),
\f4pcreate\fP(2),
\f4ptrace\fP(2),
\f4semop\fP(2),
\f4sigaction\fP(2),
\f4signal\fP(2),
\f4sigpending\fP(2),
\f4sigprocmask\fP(2),
\f4sigset\fP(2),
\f4sproc\fP(2),
\f4sysconf\fP(2),
\f4times\fP(2),
\f4ulimit\fP(2),
\f4umask\fP(2),
\f4lockf\fP(3C),
\f4signal\fP(3B),
\f4sigvec\fP(3B),
\f4system\fP(3S),
\f4a.out\fP(4),
\f4proc\fP(4),
\f4environ\fP(5)
.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.