xref: /illumos-gate/usr/src/man/man2/exec.2 (revision 0250c53ad267726f2438e3c6556199a0bbf588a2)

.\"
.\" 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 2014 Garrett D'Amore <garrett@damore.org>
.\" Copyright 2015, Joyent, Inc.
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd June 21, 2024
.Dt EXEC 2
.Os
.Sh NAME
.Nm exec ,
.Nm execl ,
.Nm execle ,
.Nm execlp ,
.Nm execv ,
.Nm execve ,
.Nm execvp ,
.Nm execvpe ,
.Nm fexecve
.Nd execute a file
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fo execl
.Fa "const char *path"
.Fa "const char *arg0"
.Fa "..."
.Fa NULL
.Fc
.Ft int
.Fo execv
.Fa "const char *path"
.Fa "char *const argv[]"
.Fc
.Ft int
.Fo execle
.Fa "const char *path"
.Fa "const char *arg0"
.Fa "..."
.Fa NULL
.Fa "char *const envp[]"
.Fc
.Ft int
.Fo execve
.Fa "const char *path"
.Fa "char *const argv[]"
.Fa "char *const envp[]"
.Fc
.Ft int
.Fo execlp
.Fa "const char *file"
.Fa "const char *arg0"
.Fa "..."
.Fa NULL
.Fc
.Ft int
.Fo execvp
.Fa "const char *file"
.Fa "char *const argv[]"
.Fc
.Ft int
.Fo execvpe
.Fa "const char *file"
.Fa "char *const argv[]"
.Fa "char *const envp[]"
.Fc
.Ft int
.Fo fexecve
.Fa "int fd"
.Fa "char *const argv[]"
.Fa "char *const envp[]"
.Fc
.Sh DESCRIPTION
Each of the functions in the
.Nm
family replaces the current process image with a new process image.
The new image is constructed from a regular, executable file called the new
process image file.
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.
.Pp
An interpreter file begins with a line of the form
.Pp
.Dl #! Pa pathname Op Ar arg
.Pp
where
.Pa pathname
is the path of the interpreter, and
.Ar arg
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
.Fa arg0
to the interpreter.
If
.Ar arg
was specified in the interpreter file, it is passed as
.Fa arg1
to the interpreter.
The remaining arguments to the interpreter are
.Fa arg0
through
.Fa argn
of the originally exec'd file.
The interpreter named by
.Pa pathname
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.
.Pp
When a C-language program is executed as a result of this call, it is entered
as a C-language function call as follows:
.Pp
.Dl int main Ns (int Fa argc Ns No , char * Ns Fa argv[])\&;
.Pp
where
.Fa argc
is the argument count and
.Fa argv
is an array of character pointers to the arguments themselves.
In addition, the following variable:
.Pp
.Dl Va "extern char **environ\&;"
.Pp
is initialized as a pointer to an array of character pointers to the
environment strings.
The
.Fa argv
and
.Va environ
arrays are each terminated by a null pointer.
The null pointer terminating the
.Fa argv
array is not counted in
.Fa argc .
.Pp
The value of
.Fa argc
is non-negative, and if greater than 0,
.Fa argv[0]
points to a string containing the name of the file.
If
.Fa argc
is 0,
.Fa argv[0]
is a null pointer, in which case there are no arguments.
Applications should verify that
.Fa argc
is greater than 0 or that
.Fa argv[0]
is not a null pointer before dereferencing
.Fa argv[0] .
.Pp
The arguments specified by a program with one of the
.Nm
functions are passed on to the new process image in the
.Fn main
arguments.
.Pp
The
.Fa path
argument points to a path name that identifies the new process image file.
.Pp
The
.Fa file
argument is used to construct a pathname that identifies the new process image
file.
If the
.Fa file
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
.Ev PATH
environment variable
.Po
see
.Xr environ 7
.Pc .
The environment is supplied typically by the shell.
If the process image file is not a valid executable object file,
.Fn execlp ,
.Fn execvp ,
and
.Fn execvpe
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
.Xr standards 7 .
.Pp
The
.Fn fexecve
function is equivalent to
.Fn execve ,
except that instead of using a named file, the file referenced by the file
descriptor
.Fa fd
is used.
Note that this file descriptor must reference a regular file which has
typically been opened with
.Dv O_EXEC .
defined in
.In fcntl.h .
The image is loaded from offset zero of the file, regardless of the offset of
fd.
.Pp
The arguments represented by
.Fa arg0 Ns No \&...
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
.Fa arg0
argument should point to a filename that is associated with the process being
started by one of the
.Nm
functions.
.Pp
The
.Fa argv
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
.Fa argv[0]
should point to a filename that is associated with the process being started by
one of the
.Nm
functions.
.Pp
The
.Fa envp
argument is an array of character pointers to null-terminated strings.
These strings constitute the environment for the new process image.
The
.Fa envp
array is terminated by a null pointer.
For
.Fn execl ,
.Fn execv ,
.Fn execvp ,
and
.Fn execlp ,
the C-language run-time start-off routine places a pointer to the environment
of the calling process in the global object
.Va extern char **environ ,
and it is used to pass the environment of the calling process to the new
process image.
.Pp
The number of bytes available for the new process's combined argument and
environment lists is
.Dv ARG_MAX .
It is implementation-dependent whether null terminators, pointers, and/or any
alignment bytes are included in this total.
.Pp
File descriptors open in the calling process image remain open in the new
process image, except for those whose close-on-exec flag
.Dv FD_CLOEXEC
is set; see
.Xr fcntl 2 .
For those file descriptors that remain open, all attributes of the open file
description, including file locks and the disposition of the close-on-fork flag
.Dv FD_CLOFORK ,
remain unchanged.
.Pp
The preferred hardware address translation size
.Po
see
.Xr memcntl 2
.Pc
for the stack and heap of the new process image are set to the default system
page size.
.Pp
Directory streams open in the calling process image are closed in the new
process image.
.Pp
The state of conversion descriptors and message catalogue descriptors in the
new process image is undefined.
For the new process, the equivalent of:
.Pp
.Dl setlocale(LC_ALL, \&"C");
.Pp
is executed at startup.
.Pp
Signals set to the default action
.Po
.Dv SIG_DFL
.Pc
in the calling process image are set to the default action in the new process
image
.Po
see
.Xr signal 3C
.Pc .
Signals set to be ignored
.Po
.Dv SIG_IGN
.Pc
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
.Po
see
.Xr signal.h 3HEAD
.Pc .
After a successful call to any of the
.Nm
functions, alternate signal stacks are not preserved and the
.Dv SA_ONSTACK
flag is cleared for all signals.
.Pp
After a successful call to any of the
.Nm
functions, any functions previously registered by
.Xr atexit 3C
are no longer registered.
.Pp
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.
.Pp
If the
.Dv ST_NOSUID
bit is set for the file system containing the new process image file, then the
effective user ID and effective group ID are unchanged in the new process
image.
If the set-user-ID mode bit of the new process image file is set
.Po
see
.Xr chmod 2
.Pc ,
the effective user ID of the new process image is set to the owner ID of the
new process image file.
Similarly, if the set-group-ID mode bit of the new process image file is set,
the effective group ID of the new process image is set to the group ID of the
new process image file.
The real user ID and real group ID 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
.Pq as the saved set-user-ID and the saved set-group-ID
for use by
.Xr setuid 2 .
.Pp
The privilege sets are changed according to the following rules:
.Bl -enum -offset indent
.It
The inheritable set, I, is intersected with the limit set, L.
This mechanism enforces the limit set for processes.
.It
The effective set, E, and the permitted set, P, are made equal to the new
inheritable set.
.El
.Pp
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
.Xr privileges 7 .
.Pp
If the
.Brq Dv PRIV_PROC_OWNER
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
.Xr ptrace 3C .
Additional restrictions can apply when the traced process has an effective UID
of 0.
See
.Xr privileges 7 .
.Pp
Any shared memory segments attached to the calling process image will not be
attached to the new process image
.Po
see
.Xr shmop 2
.Pc .
Any mappings established through
.Fn mmap
are not preserved across an
.Nm .
Memory mappings created in the process are unmapped before the address space is
rebuilt for the new process image.
See
.Xr mmap 2 .
.Pp
Memory locks established by the calling process via calls to
.Xr mlockall 3C
or
.Xr mlock 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
.Nm
function.
If the
.Nm
function fails, the effect on memory locks is unspecified.
.Pp
If
.Dv _XOPEN_REALTIME
is defined and has a value other than \-1, any named semaphores open in the
calling process are closed as if by appropriate calls to
.Xr sem_close 3C .
.Pp
Profiling is disabled for the new process; see
.Xr profil 2 .
.Pp
Timers created by the calling process with
.Xr timer_create 3C
are deleted before replacing the current process image with the new process
image.
.Pp
For the
.Dv SCHED_FIFO
and
.Dv SCHED_RR
scheduling policies, the policy and priority settings are not changed by a call
to an
.Nm
function.
.Pp
All open message queue descriptors in the calling process are closed, as
described in
.Xr mq_close 3C .
.Pp
Any outstanding asynchronous I/O operations may be cancelled.
Those asynchronous I/O operations that are not canceled will complete as if the
.Nm
function had not yet occurred, but any associated signal notifications are
suppressed.
It is unspecified whether the
.Nm
function itself blocks awaiting such I/O completion.
In no event, however, will the new process image created by the
.Nm
function be affected by the presence of outstanding asynchronous I/O operations
at the time the
.Nm
function is called.
.Pp
All active contract templates are cleared
.Po
see
.Xr contract 5
.Pc .
.Pp
The new process also inherits the following attributes from the calling process:
.Bl -bullet -offset Ds
.It
controlling terminal
.It
current working directory
.It
file-locks
.Po
see
.Xr fcntl 2
and
.Xr lockf 3C
.Pc
.It
file mode creation mask
.Po
see
.Xr umask 2
.Pc
.It
file size limit
.Po
see
.Xr ulimit 2
.Pc
.It
limit privilege set
.It
nice value
.Po
see
.Xr nice 2
.Pc
.It
parent process ID
.It
pending signals
.Po
see
.Xr sigpending 2
.Pc
.It
privilege debugging flag
.Po
see
.Xr privileges 7
and
.Xr getpflags 2
.Pc
.It
process ID
.It
process contract
.Po
see
.Xr contract 5
and
.Xr process 5
.Pc
.It
process group ID
.It
process signal mask
.Po
see
.Xr sigprocmask 2
.Pc
.It
processor bindings
.Po
see
.Xr processor_bind 2
.Pc
.It
processor set bindings
.Po
see
.Xr pset_bind 2
.Pc
.It
project ID
.It
real group ID
.It
real user ID
.It
resource limits
.Po
see
.Xr getrlimit 2
.Pc
.It
root directory
.It
scheduler class and priority
.Po
see
.Xr priocntl 2
.Pc
.It
semadj values
.Po
see
.Xr semop 2
.Pc
.It
session membership
.Po
see
.Xr exit 2
and
.Xr signal 3C
.Pc
.It
supplementary group IDs
.It
task ID
.It
time left until an alarm clock signal
.Po
see
.Xr alarm 2
.Pc
.It
.Fa tms_utime ,
.Fa tms_stime ,
.Fa tms_cutime ,
and
.Fa tms_cstime
.Po
see
.Xr times 2
.Pc
.It
trace flag
.Po
see
.Xr ptrace 3C
request 0
.Pc
.El
.Pp
A call to any
.Nm
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.
.Pp
Upon successful completion, each of the functions in the
.Nm
family marks for update the
.Fa st_atime
field of the file.
If an
.Nm
function failed but was able to locate the process image file, whether the
.Fa st_atime
field is marked for update is unspecified.
Should the function succeed, the process image file is considered to have been
opened with
.Xr open 2 .
The corresponding
.Xr close 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
.Nm
functions.
The
.Fa argv[]
and
.Fa envp[]
arrays of pointers and the strings to which those arrays point will not be
modified by a call to one of the
.Nm
functions, except as a consequence of replacing the process image.
.Pp
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
If a function in the
.Nm
family returns to the calling process image, an error has occurred; the return
value is \-1 and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Nm
functions will fail if:
.Bl -tag -width Er
.It Er E2BIG
The number of bytes in the new process's argument list is greater than the
system-imposed limit of
.Dv 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.
.It Er EACCES
Search permission is denied for a directory listed in the new process file's
path prefix.
.Pp
The new process file is not an ordinary file.
.Pp
The new process file mode denies execute permission.
.Pp
The
.Brq Dv FILE_DAC_SEARCH
privilege overrides the restriction on directory searches.
.Pp
The
.Brq Dv FILE_DAC_EXECUTE
privilege overrides the lack of execute permission.
.It Er EAGAIN
Total amount of system memory available when reading using raw I/O is
temporarily insufficient.
.It Er EFAULT
An argument points to an illegal address.
.It Er EINVAL
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.
.It Er EINTR
A signal was caught during the execution of one of the functions in the
.Nm
family.
.El
.Pp
The
.Nm
functions except for
.Fn fexecve
will fail if:
.Bl -tag -width Ds
.It Er ELOOP
Too many symbolic links were encountered in translating
.Fa path
or
.Fa file ,
or too many nested interpreter files.
.It Er ENAMETOOLONG
The length of the
.Fa file
or
.Fa path
argument exceeds
.Dv PATH_MAX ,
or the length of a
.Fa file
or
.Fa path
component exceeds
.Dv NAME_MAX
while
.Dv _POSIX_NO_TRUNC
is in effect.
.It Er ENOENT
One or more components of the new process path name of the file do not exist or
is a null pathname.
.It Er ENOLINK
The
.Fa path
argument points to a remote machine and the link to that machine is no longer
active.
.It Er ENOTDIR
A component of the new process path of the file prefix is not a directory.
.El
.Pp
The
.Nm
functions, except for
.Fn execlp ,
.Fn execvp ,
and
.Fn execvpe ,
will fail if:
.Bl -tag -width Ds
.It Er ENOEXEC
The new process image file has the appropriate access permission but is not in
the proper format.
.El
.Pp
The
.Fn fexecve
function will fail if:
.Bl -tag -width Ds
.It Er EBADF
The
.Fa fd
argument is not a valid file descriptor opened for execution.
.It Er ENOMEM
There was insufficient memory for constructing the path corresponding to the
file descriptor.
.El
.Pp
The
.Nm
functions except for
.Fn fexecve
may fail if:
.Bl -tag -width Ds
.It Er ENAMETOOLONG
Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds
.Dv PATH_MAX .
.El
.Pp
The
.Nm
functions may fail if:
.Bl -tag -width Ds
.It Er ENOMEM
The new process image requires more memory than is allowed by the hardware or
system-imposed by memory management constraints.
See
.Xr brk 2 .
.It Er ETXTBSY
The new process image file is a pure procedure
.Pq shared text
file that is currently open for writing by some process.
.El
.Sh USAGE
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
.Nm
functions.
.Pp
Applications that require other than the default POSIX locale should call
.Xr setlocale 3C
with the appropriate parameters to establish the locale of the new process.
.Pp
The
.Fa environ
array should not be accessed directly by the application.
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
The
.Fn execle ,
.Fn execve
and
.Fn fexecve
functions are
.Sy Async-Signal-Safe
.Sh SEE ALSO
.Xr ksh 1 ,
.Xr ps 1 ,
.Xr sh 1 ,
.Xr alarm 2 ,
.Xr brk 2 ,
.Xr chmod 2 ,
.Xr close 2 ,
.Xr exit 2 ,
.Xr fcntl 2 ,
.Xr fork 2 ,
.Xr getpflags 2 ,
.Xr getrlimit 2 ,
.Xr memcntl 2 ,
.Xr mmap 2 ,
.Xr nice 2 ,
.Xr open 2 ,
.Xr priocntl 2 ,
.Xr processor_bind 2 ,
.Xr profil 2 ,
.Xr pset_bind 2 ,
.Xr semop 2 ,
.Xr setuid 2 ,
.Xr shmop 2 ,
.Xr sigpending 2 ,
.Xr sigprocmask 2 ,
.Xr times 2 ,
.Xr ulimit 2 ,
.Xr umask 2 ,
.Xr atexit 3C ,
.Xr lockf 3C ,
.Xr mlock 3C ,
.Xr mlockall 3C ,
.Xr mq_close 3C ,
.Xr ptrace 3C ,
.Xr sem_close 3C ,
.Xr setlocale 3C ,
.Xr signal 3C ,
.Xr system 3C ,
.Xr timer_create 3C ,
.Xr signal.h 3HEAD ,
.Xr a.out 5 ,
.Xr contract 5 ,
.Xr process 5 ,
.Xr attributes 7 ,
.Xr environ 7 ,
.Xr privileges 7 ,
.Xr standards 7
.Sh WARNINGS
If a program is setuid to a user ID other than the superuser, and the program
is executed when the real user ID is super-user, then the program has some of
the powers of a super-user as well.