path: root/usr/src/man/man2/exec.2

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T.
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2015, Joyent, Inc.
.\"
.TH EXEC 2 "Oct 27, 2015"
.SH NAME
exec, execl, execle, execlp, execv, execve, execvp \- execute a file
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>

\fBint\fR \fBexecl\fR(\fBconst char *\fR\fIpath\fR, \fBconst char *\fR\fIarg0\fR, \fB\&...
     /* const char *\fR\fIargn\fR, \fB(char *)0 */);\fR
.fi

.LP
.nf
\fBint\fR \fBexecv\fR(\fBconst char *\fR\fIpath\fR, \fBchar *const\fR \fIargv[]\fR);
.fi

.LP
.nf
\fBint\fR \fBexecle\fR(\fBconst char *\fR\fIpath\fR, \fBconst char *\fR\fIarg0\fR, \fB\&...
     /* const char *\fR\fIargn\fR, \fB(char *)0\fR,\fBchar *const\fR \fIenvp\fR[]*/);
.fi

.LP
.nf
\fBint\fR \fBexecve\fR(\fBconst char *\fR\fIpath\fR, \fBchar *const\fR \fIargv[]\fR,
     \fBchar *const\fR \fIenvp[]\fR);
.fi

.LP
.nf
\fBint\fR \fBexeclp\fR(\fBconst char *\fR\fIfile\fR, \fBconst char *\fR\fIarg0\fR, \fB\&...
     /* const char *\fR\fIargn\fR, \fB(char *)0 */);\fR
.fi

.LP
.nf
\fBint\fR \fBexecvp\fR(\fBconst char *\fR\fIfile\fR, \fBchar *const\fR \fIargv[]\fR);
.fi

.SH DESCRIPTION
.LP
Each of the functions in the \fBexec\fR family replaces the current process
image with a new process image. The new image is constructed from a regular,
executable file called the \fBnew process image file\fR. This file is either an
executable object file or a file of data for an interpreter. There is no return
from a successful call to one of these functions because the calling process
image is overlaid by the new process image.
.sp
.LP
An interpreter file begins with a line of the form
.sp
.in +2
.nf
#! pathname [\fIarg\fR]
.fi
.in -2

.sp
.LP
where \fIpathname\fR is the path of the interpreter, and \fIarg\fR is an
optional argument. When an interpreter file is executed, the system invokes the
specified interpreter. The pathname specified in the interpreter file is passed
as \fIarg0\fR to the interpreter. If \fIarg\fR was specified in the interpreter
file, it is passed as \fIarg1\fR to the interpreter. The remaining arguments to
the interpreter are \fIarg0\fR through \fIargn\fR of the originally exec'd
file. The interpreter named by \fIpathname\fR may also be an interpreter file.
There can be up to four nested interpreter files before the final interpreter.
The setid bits on nested interpreters are silently ignored.
.sp
.LP
When a C-language program is executed as a result of this call, it is entered
as a C-language function call as follows:
.sp
.in +2
.nf
int main (int argc, char *argv[]);
.fi
.in -2

.sp
.LP
where \fIargc\fR is the argument count and \fIargv\fR is an array of character
pointers to the arguments themselves. In addition, the following variable:
.sp
.in +2
.nf
extern char **environ;
.fi
.in -2

.sp
.LP
is initialized as a pointer to an array of character pointers to the
environment strings. The \fIargv\fR and \fIenviron\fR arrays are each
terminated by a null pointer. The null pointer terminating the \fIargv\fR array
is not counted in \fIargc\fR.
.sp
.LP
The value of \fIargc\fR is non-negative, and if greater than 0, \fIargv\fR[0]
points to a string containing the name of the file. If \fIargc\fR is 0,
\fIargv\fR[0] is a null pointer, in which case there are no arguments.
Applications should verify that \fIargc\fR is greater than 0 or that
\fIargv\fR[0] is not a null pointer before dereferencing \fIargv\fR[0].
.sp
.LP
The arguments specified by a program with one of the \fBexec\fR functions are
passed on to the new process image in the \fBmain()\fR arguments.
.sp
.LP
The \fIpath\fR argument points to a path name that identifies the new process
image file.
.sp
.LP
The \fIfile\fR argument is used to construct a pathname that identifies the new
process image file. If the \fIfile\fR argument contains a slash character, it
is used as the pathname for this file. Otherwise, the path prefix for this file
is obtained by a search of the directories passed in the \fBPATH\fR environment
variable (see \fBenviron\fR(7)). The environment is supplied typically by the
shell. If the process image file is not a valid executable object file,
\fBexeclp()\fR and \fBexecvp()\fR use the contents of that file as standard
input to the shell. In this case, the shell becomes the new process image. The
standard to which the caller conforms determines which shell is used. See
\fBstandards\fR(7).
.sp
.LP
The arguments represented by \fIarg0\fR\&.\|.\|. are pointers to
null-terminated character strings. These strings constitute the argument list
available to the new process image. The list is terminated by a null pointer.
The \fIarg0\fR argument should point to a filename that is associated with the
process being started by one of the \fBexec\fR functions.
.sp
.LP
The \fIargv\fR argument is an array of character pointers to null-terminated
strings. The last member of this array must be a null pointer. These strings
constitute the argument list available to the new process image. The value in
\fIargv\fR[0] should point to a filename that is associated with the process
being started by one of the \fBexec\fR functions.
.sp
.LP
The \fIenvp\fR argument is an array of character pointers to null-terminated
strings. These strings constitute the environment for the new process image.
The \fIenvp\fR array is terminated by a null pointer. For \fBexecl()\fR,
\fBexecv()\fR, \fBexecvp()\fR, and \fBexeclp()\fR, the C-language run-time
start-off routine places a pointer to the environment of the calling process in
the global object \fBextern char **environ\fR, and it is used to pass the
environment of the calling process to the new process image.
.sp
.LP
The number of bytes available for the new process's combined argument and
environment lists is \fBARG_MAX\fR. It is implementation-dependent whether null
terminators, pointers, and/or any alignment bytes are included in this total.
.sp
.LP
File descriptors open in the calling process image remain open in the new
process image, except for those whose close-on-exec flag \fBFD_CLOEXEC\fR is
set; see \fBfcntl\fR(2). For those file descriptors that remain open, all
attributes of the open file description, including file locks, remain
unchanged.
.sp
.LP
The preferred hardware address translation size (see \fBmemcntl\fR(2)) for the
stack and heap of the new process image are set to the default system page
size.
.sp
.LP
Directory streams open in the calling process image are closed in the new
process image.
.sp
.LP
The state of conversion descriptors and message catalogue descriptors in the
new process image is undefined. For the new process, the equivalent of:
.sp
.in +2
.nf
setlocale(LC_ALL, "C")
.fi
.in -2

.sp
.LP
is executed at startup.
.sp
.LP
Signals set to the default action (\fBSIG_DFL\fR) in the calling process image
are set to the default action in the new process image (see \fBsignal\fR(3C)).
Signals set to be ignored (\fBSIG_IGN\fR) by the calling process image are set
to be ignored by the new process image. Signals set to be caught by the calling
process image are set to the default action in the new process image (see
\fBsignal.h\fR(3HEAD)). After a successful call to any of the \fBexec\fR
functions, alternate signal stacks are not preserved and the \fBSA_ONSTACK\fR
flag is cleared for all signals.
.sp
.LP
After a successful call to any of the \fBexec\fR functions, any functions
previously registered by \fBatexit\fR(3C) are no longer registered.
.sp
.LP
The saved resource limits in the new process image are set to be a copy of the
process's corresponding hard and soft resource limits.
.sp
.LP
If the \fBST_NOSUID\fR bit is set for the file system containing the new
process image file, then the effective user \fBID\fR and effective group
\fBID\fR are unchanged in the new process image. If the set-user-\fBID\fR mode
bit of the new process image file is set (see \fBchmod\fR(2)), the effective
user \fBID\fR of the new process image is set to the owner \fBID\fR of the new
process image file. Similarly, if the set-group-\fBID\fR mode bit of the new
process image file is set, the effective group \fBID\fR of the new process
image is set to the group \fBID\fR of the new process image file. The real user
\fBID\fR and real group \fBID\fR of the new process image remain the same as
those of the calling process image. The effective user ID and effective group
ID of the new process image are saved (as the saved set-user-ID and the saved
set-group-ID for use by \fBsetuid\fR(2).
.sp
.LP
The privilege sets are changed according to the following rules:
.RS +4
.TP
1.
The inheritable set, I, is intersected with the limit set, L.  This
mechanism enforces the limit set for processes.
.RE
.RS +4
.TP
2.
The effective set, E, and the permitted set, P, are made equal to the new
inheritable set.
.RE
.sp
.LP
The system attempts to set the privilege-aware state to non-PA both before
performing any modifications to the process IDs and privilege sets as well as
after completing the transition to new UIDs and privilege sets, following the
rules outlined in \fBprivileges\fR(7).
.sp
.LP
If the {\fBPRIV_PROC_OWNER\fR} privilege is asserted in the effective set, the
set-user-ID and set-group-ID bits will be honored when the process is being
controlled by \fBptrace\fR(3C). Additional restriction can apply when the
traced process has an effective UID of 0. See \fBprivileges\fR(7).
.sp
.LP
Any shared memory segments attached to the calling process image will not be
attached to the new process image (see \fBshmop\fR(2)). Any mappings
established through \fBmmap()\fR are not preserved across an \fBexec\fR. Memory
mappings created in the process are unmapped before the address space is
rebuilt for the new process image. See \fBmmap\fR(2).
.sp
.LP
Memory locks established by the calling process via calls to \fBmlockall\fR(3C)
or \fBmlock\fR(3C) are removed. If locked pages in the address space of the
calling process are also mapped into the address spaces the locks established
by the other processes will be unaffected by the call by this process to the
\fBexec\fR function. If the \fBexec\fR function fails, the effect on memory
locks is unspecified.
.sp
.LP
If \fB_XOPEN_REALTIME\fR is defined and has a value other than \(mi1, any named
semaphores open in the calling process are closed as if by appropriate calls to
.BR sem_close (3C)
.sp
.LP
Profiling is disabled for the new process; see \fBprofil\fR(2).
.sp
.LP
Timers created by the calling process with \fBtimer_create\fR(3C) are deleted
before replacing the current process image with the new process image.
.sp
.LP
For the \fBSCHED_FIFO\fR and \fBSCHED_RR\fR scheduling policies, the policy and
priority settings are not changed by a call to an \fBexec\fR function.
.sp
.LP
All open message queue descriptors in the calling process are closed, as
described in \fBmq_close\fR(3C).
.sp
.LP
Any outstanding asynchronous I/O operations may be cancelled. Those
asynchronous I/O operations that are not canceled will complete as if the
\fBexec\fR function had not yet occurred, but any associated signal
notifications are suppressed. It is unspecified whether the \fBexec\fR function
itself blocks awaiting such I/O completion. In no event, however, will the new
process image created by the \fBexec\fR function be affected by the presence of
outstanding asynchronous I/O operations at the time the \fBexec\fR function is
called.
.sp
.LP
All active contract templates are cleared (see \fBcontract\fR(5)).
.sp
.LP
The new process also inherits the following attributes from the calling
process:
.RS +4
.TP
.ie t \(bu
.el o
controlling terminal
.RE
.RS +4
.TP
.ie t \(bu
.el o
current working directory
.RE
.RS +4
.TP
.ie t \(bu
.el o
file-locks (see \fBfcntl\fR(2) and \fBlockf\fR(3C))
.RE
.RS +4
.TP
.ie t \(bu
.el o
file mode creation mask (see \fBumask\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
file size limit (see \fBulimit\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
limit privilege set
.RE
.RS +4
.TP
.ie t \(bu
.el o
nice value (see \fBnice\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
parent process \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
pending signals (see \fBsigpending\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
privilege debugging flag (see \fBprivileges\fR(7) and \fBgetpflags\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
process \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
process contract (see \fBcontract\fR(5) and \fBprocess\fR(5))
.RE
.RS +4
.TP
.ie t \(bu
.el o
process group \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
process signal mask (see \fBsigprocmask\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
processor bindings (see \fBprocessor_bind\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
processor set bindings (see \fBpset_bind\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
project \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
real group \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
real user \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
resource limits (see \fBgetrlimit\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
root directory
.RE
.RS +4
.TP
.ie t \(bu
.el o
scheduler class and priority (see \fBpriocntl\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBsemadj\fR values (see \fBsemop\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
session membership (see \fBexit\fR(2) and \fBsignal\fR(3C))
.RE
.RS +4
.TP
.ie t \(bu
.el o
supplementary group \fBIDs\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
task \fBID\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
time left until an alarm clock signal (see \fBalarm\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBtms_utime\fR, \fBtms_stime\fR, \fBtms_cutime\fR, and \fBtms_cstime\fR (see
\fBtimes\fR(2))
.RE
.RS +4
.TP
.ie t \(bu
.el o
trace flag (see \fBptrace\fR(3C) request 0)
.RE
.sp
.LP
A call to any \fBexec\fR function from a process with more than one thread
results in all threads being terminated and the new executable image being
loaded and executed. No destructor functions will be called.
.sp
.LP
Upon successful completion, each of the functions in the \fBexec\fR family
marks for update the \fBst_atime\fR field of the file.  If an \fBexec\fR
function failed but was able to locate the \fBprocess image file\fR, whether
the \fBst_atime\fR field is marked for update is unspecified. Should the
function succeed, the process image file is considered to have been opened with
\fBopen\fR(2). The corresponding \fBclose\fR(2) is considered to occur at a
time after this open, but before process termination or successful completion
of a subsequent call to one of the \fBexec\fR functions. The \fIargv\fR[\|] and
\fIenvp\fR[\|] arrays of pointers and the strings to which those arrays point
will not be modified by a call to one of the \fBexec\fR functions, except as a
consequence of replacing the process image.
.sp
.LP
The saved resource limits in the new process image are set to be a copy of the
process's corresponding hard and soft limits.
.SH RETURN VALUES
.LP
If a function in the \fBexec\fR family returns to the calling process image, an
error has occurred; the return value is \fB\(mi1\fR and \fBerrno\fR is set to
indicate the error.
.SH ERRORS
.LP
The \fBexec\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBE2BIG\fR\fR
.ad
.RS 16n
The number of bytes in the new process's argument list is greater than the
system-imposed limit of {\fBARG_MAX\fR} bytes. The argument list limit is sum
of the size of the argument list plus the size of the environment's exported
shell variables.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 16n
Search permission is denied for a directory listed in the new process file's
path prefix.
.sp
The new process file is not an ordinary file.
.sp
The new process file mode denies execute permission.
.sp
The {\fBFILE_DAC_SEARCH\fR} privilege overrides the restriction on directory
searches.
.sp
The {\fBFILE_DAC_EXECUTE\fR} privilege overrides the lack of execute
permission.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 16n
Total amount of system memory available when reading using raw I/O is
temporarily insufficient.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 16n
An argument points to an illegal address.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 16n
The new process image file has the appropriate permission and has a recognized
executable binary format, but the system does not support execution of a file
with this format.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 16n
A signal was caught during the execution of one of the functions in the
\fIexec\fR family.
.RE

.sp
.ne 2
.na
\fB\fBELOOP\fR\fR
.ad
.RS 16n
Too many symbolic links were encountered in translating \fIpath\fR or
\fIfile\fR, or too many nested interpreter files.
.RE

.sp
.ne 2
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
The length of the \fIfile\fR or \fIpath\fR argument exceeds {\fBPATH_MAX\fR},
or the length of a \fIfile\fR or \fIpath\fR component exceeds {\fBNAME_MAX\fR}
while {\fB_POSIX_NO_TRUNC\fR} is in effect.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 16n
One or more components of the new process path name of the file do not exist or
is a null pathname.
.RE

.sp
.ne 2
.na
\fB\fBENOLINK\fR\fR
.ad
.RS 16n
The \fIpath\fR argument points to a remote machine and the link to that machine
is no longer active.
.RE

.sp
.ne 2
.na
\fB\fBENOTDIR\fR\fR
.ad
.RS 16n
A component of the new process path of the file prefix is not a directory.
.RE

.sp
.LP
The \fBexec\fR functions, except for \fBexeclp()\fR and \fBexecvp()\fR, will
fail if:
.sp
.ne 2
.na
\fB\fBENOEXEC\fR\fR
.ad
.RS 11n
The new process image file has the appropriate access permission but is not in
the proper format.
.RE

.sp
.LP
The \fBexec\fR functions may fail if:
.sp
.ne 2
.na
\fB\fBENAMETOOLONG\fR\fR
.ad
.RS 16n
Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {\fBPATH_MAX\fR}.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 16n
The new process image requires more memory than is allowed by the hardware or
system-imposed by memory management constraints. See \fBbrk\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBETXTBSY\fR\fR
.ad
.RS 16n
The new process image file is a pure procedure (shared text) file that is
currently open for writing by some process.
.RE

.SH USAGE
.LP
As the state of conversion descriptors and message catalogue descriptors in the
new process image is undefined, portable applications should not rely on their
use and should close them prior to calling one of the \fBexec\fR functions.
.sp
.LP
Applications that require other than the default POSIX locale should call
\fBsetlocale\fR(3C) with the appropriate parameters to establish the locale of
thenew process.
.sp
.LP
The \fIenviron\fR array should not be accessed directly by the application.
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	See below.
_
Standard	See \fBstandards\fR(7).
.TE

.sp
.LP
The \fBexecle()\fR and \fBexecve()\fR functions are Async-Signal-Safe.
.SH SEE ALSO
.LP
.BR ksh (1),
.BR ps (1),
.BR sh (1),
.BR alarm (2),
.BR brk (2),
.BR chmod (2),
.BR exit (2),
.BR fcntl (2),
.BR fork (2),
.BR getpflags (2),
.BR getrlimit (2),
.BR memcntl (2),
.BR mmap (2),
.BR nice (2),
.BR priocntl (2),
.BR profil (2),
.BR semop (2),
.BR shmop (2),
.BR sigpending (2),
.BR sigprocmask (2),
.BR times (2),
.BR umask (2),
.BR lockf (3C),
.BR ptrace (3C),
.BR setlocale (3C),
.BR signal (3C),
.BR system (3C),
.BR timer_create (3C),
.BR a.out (5),
.BR contract (5),
.BR process (5),
.BR attributes (7),
.BR environ (7),
.BR privileges (7),
.BR standards (7)
.SH WARNINGS
.LP
If a program is \fBsetuid\fR to a user \fBID\fR other than the superuser, and
the program is executed when the real user \fBID\fR is super-user, then the
program has some of the powers of a super-user as well.