349 lines
9.8 KiB
Groff
349 lines
9.8 KiB
Groff
|
.\" $OpenBSD: execve.2,v 1.58 2022/10/13 21:37:05 jmc Exp $
|
||
|
.\" $NetBSD: execve.2,v 1.9 1995/02/27 12:32:25 cgd Exp $
|
||
|
.\"
|
||
|
.\" Copyright (c) 1980, 1991, 1993
|
||
|
.\" The Regents of the University of California. All rights reserved.
|
||
|
.\"
|
||
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
.\" modification, are permitted provided that the following conditions
|
||
|
.\" are met:
|
||
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
.\" 3. Neither the name of the University nor the names of its contributors
|
||
|
.\" may be used to endorse or promote products derived from this software
|
||
|
.\" without specific prior written permission.
|
||
|
.\"
|
||
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
|
.\" SUCH DAMAGE.
|
||
|
.\"
|
||
|
.\" @(#)execve.2 8.3 (Berkeley) 1/24/94
|
||
|
.\"
|
||
|
.Dd $Mdocdate: October 13 2022 $
|
||
|
.Dt EXECVE 2
|
||
|
.Os
|
||
|
.Sh NAME
|
||
|
.Nm execve
|
||
|
.Nd execute a file
|
||
|
.Sh SYNOPSIS
|
||
|
.In unistd.h
|
||
|
.Ft int
|
||
|
.Fn execve "const char *path" "char *const argv[]" "char *const envp[]"
|
||
|
.Sh DESCRIPTION
|
||
|
.Fn execve
|
||
|
transforms the calling process into a new process.
|
||
|
The new process is constructed from an ordinary file,
|
||
|
whose name is pointed to by
|
||
|
.Fa path ,
|
||
|
called the
|
||
|
.Em new process file .
|
||
|
This file is either an executable object file,
|
||
|
or a file of data for an interpreter.
|
||
|
An executable object file consists of an identifying header,
|
||
|
followed by pages of data representing the initial program (text)
|
||
|
and initialized data pages.
|
||
|
Additional pages may be specified by the header to be initialized
|
||
|
with zero data; see
|
||
|
.Xr elf 5 .
|
||
|
.Pp
|
||
|
An interpreter file begins with a line of the form:
|
||
|
.Pp
|
||
|
.D1 #! Ar interpreter Op Ar arg
|
||
|
.Pp
|
||
|
When an interpreter file is passed to
|
||
|
.Fn execve ,
|
||
|
the system instead calls
|
||
|
.Fn execve
|
||
|
with the specified
|
||
|
.Ar interpreter .
|
||
|
If the optional
|
||
|
.Ar arg
|
||
|
is specified, it becomes the first argument to the
|
||
|
.Ar interpreter ,
|
||
|
and the original
|
||
|
.Fa path
|
||
|
becomes the second argument;
|
||
|
otherwise,
|
||
|
.Fa path
|
||
|
becomes the first argument.
|
||
|
The original arguments are shifted over to become the subsequent arguments.
|
||
|
The zeroth argument, normally the name of the file being executed, is left
|
||
|
unchanged.
|
||
|
.Pp
|
||
|
The argument
|
||
|
.Fa argv
|
||
|
is a pointer to a null-terminated array of
|
||
|
character pointers to NUL-terminated character strings.
|
||
|
These strings construct the argument list to be made available to the new
|
||
|
process.
|
||
|
At least one non-null argument must be present in the array;
|
||
|
by custom, the first element should be
|
||
|
the name of the executed program (for example, the last component of
|
||
|
.Fa path ) .
|
||
|
.Pp
|
||
|
The argument
|
||
|
.Fa envp
|
||
|
is also a pointer to a null-terminated array of
|
||
|
character pointers to NUL-terminated strings.
|
||
|
A pointer to this array is normally stored in the global variable
|
||
|
.Va environ .
|
||
|
These strings pass information to the
|
||
|
new process that is not directly an argument to the command (see
|
||
|
.Xr environ 7 ) .
|
||
|
.Pp
|
||
|
File descriptors open in the calling process image remain open in
|
||
|
the new process image, except for those for which the close-on-exec
|
||
|
flag is set (see
|
||
|
.Xr close 2
|
||
|
and
|
||
|
.Xr fcntl 2 ) .
|
||
|
Descriptors that remain open are unaffected by
|
||
|
.Fn execve .
|
||
|
In the case of a new setuid or setgid executable being executed, if
|
||
|
file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr)
|
||
|
are currently unallocated, these descriptors will be opened to point to
|
||
|
some system file like
|
||
|
.Pa /dev/null .
|
||
|
The intent is to ensure these descriptors are not unallocated, since
|
||
|
many libraries make assumptions about the use of these 3 file descriptors.
|
||
|
.Pp
|
||
|
Signals set to be ignored in the calling process,
|
||
|
with the exception of
|
||
|
.Dv SIGCHLD ,
|
||
|
are set to be ignored in
|
||
|
the
|
||
|
new process.
|
||
|
Other signals
|
||
|
are set to default action in the new process image.
|
||
|
Blocked signals remain blocked regardless of changes to the signal action.
|
||
|
The signal stack is reset to be undefined (see
|
||
|
.Xr sigaction 2
|
||
|
for more information).
|
||
|
.Pp
|
||
|
If the set-user-ID mode bit of the new process image file is set
|
||
|
(see
|
||
|
.Xr chmod 2 ) ,
|
||
|
the effective user ID of the new process image is set to the owner ID
|
||
|
of the new process image file.
|
||
|
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 effective group ID is the first element of the group list.)
|
||
|
The real user ID, real group ID and
|
||
|
other group IDs of the new process image remain the same as the calling
|
||
|
process image.
|
||
|
After any set-user-ID and set-group-ID processing,
|
||
|
the effective user ID is recorded as the saved set-user-ID,
|
||
|
and the effective group ID is recorded as the saved set-group-ID.
|
||
|
These values may be used in changing the effective IDs later (see
|
||
|
.Xr setuid 2 ) .
|
||
|
The set-user-ID and set-group-ID bits have no effect if the
|
||
|
new process image file is located on a file system mounted with
|
||
|
the nosuid flag.
|
||
|
The process will be started without the new permissions.
|
||
|
.Pp
|
||
|
The new process also inherits the following attributes from
|
||
|
the calling process:
|
||
|
.Pp
|
||
|
.Bl -tag -width controlling_terminal -offset indent -compact
|
||
|
.It process ID
|
||
|
see
|
||
|
.Xr getpid 2
|
||
|
.It parent process ID
|
||
|
see
|
||
|
.Xr getppid 2
|
||
|
.It process group ID
|
||
|
see
|
||
|
.Xr getpgrp 2
|
||
|
.It session ID
|
||
|
see
|
||
|
.Xr getsid 2
|
||
|
.It access groups
|
||
|
see
|
||
|
.Xr getgroups 2
|
||
|
.It working directory
|
||
|
see
|
||
|
.Xr chdir 2
|
||
|
.It root directory
|
||
|
see
|
||
|
.Xr chroot 2
|
||
|
.It controlling terminal
|
||
|
see
|
||
|
.Xr termios 4
|
||
|
.It resource usages
|
||
|
see
|
||
|
.Xr getrusage 2
|
||
|
.It interval timers
|
||
|
see
|
||
|
.Xr getitimer 2
|
||
|
(unless process image file is setuid or setgid,
|
||
|
in which case all timers are disabled)
|
||
|
.It resource limits
|
||
|
see
|
||
|
.Xr getrlimit 2
|
||
|
.It file mode mask
|
||
|
see
|
||
|
.Xr umask 2
|
||
|
.It signal mask
|
||
|
see
|
||
|
.Xr sigaction 2 ,
|
||
|
.Xr sigprocmask 2
|
||
|
.El
|
||
|
.Pp
|
||
|
When a program is executed as a result of an
|
||
|
.Fn execve
|
||
|
call, it is entered as follows:
|
||
|
.Pp
|
||
|
.Dl main(int argc, char **argv, char **envp)
|
||
|
.Pp
|
||
|
where
|
||
|
.Fa argc
|
||
|
is the number of elements in
|
||
|
.Fa argv
|
||
|
(the
|
||
|
.Dq arg count )
|
||
|
and
|
||
|
.Fa argv
|
||
|
points to the array of character pointers
|
||
|
to the arguments themselves.
|
||
|
.Sh RETURN VALUES
|
||
|
As the
|
||
|
.Fn execve
|
||
|
function overlays the current process image
|
||
|
with a new process image, the successful call
|
||
|
has no process to return to.
|
||
|
If
|
||
|
.Fn execve
|
||
|
does return to the calling process, an error has occurred; the
|
||
|
return value will be \-1 and the global variable
|
||
|
.Va errno
|
||
|
is set to indicate the error.
|
||
|
.Sh ERRORS
|
||
|
.Fn execve
|
||
|
will fail and return to the calling process if:
|
||
|
.Bl -tag -width Er
|
||
|
.It Bq Er ENOTDIR
|
||
|
A component of the path prefix is not a directory.
|
||
|
.It Bq Er ENAMETOOLONG
|
||
|
A component of a pathname exceeded
|
||
|
.Dv NAME_MAX
|
||
|
characters, or an entire pathname (including the terminating NUL)
|
||
|
exceeded
|
||
|
.Dv PATH_MAX
|
||
|
bytes.
|
||
|
.It Bq Er ENOENT
|
||
|
The new process file does not exist.
|
||
|
.It Bq Er ELOOP
|
||
|
Too many symbolic links were encountered in translating the pathname.
|
||
|
.It Bq Er EACCES
|
||
|
Search permission is denied for a component of the path prefix.
|
||
|
.It Bq Er EACCES
|
||
|
The new process file is not an ordinary file.
|
||
|
.It Bq Er EACCES
|
||
|
The new process file mode denies execute permission.
|
||
|
.It Bq Er EACCES
|
||
|
The new process file is on a filesystem mounted with execution
|
||
|
disabled
|
||
|
.Pf ( Dv MNT_NOEXEC
|
||
|
in
|
||
|
.In sys/mount.h ) .
|
||
|
.It Bq Er EACCES
|
||
|
The new process file is marked with
|
||
|
.Xr ld 1
|
||
|
.Fl z Cm wxneeded
|
||
|
to perform W^X violating operations, but it is located on a file
|
||
|
system not allowing such operations, being mounted without the
|
||
|
.Xr mount 8
|
||
|
.Fl o Cm wxallowed
|
||
|
flag.
|
||
|
.It Bq Er EACCES
|
||
|
The parent used
|
||
|
.Xr pledge 2
|
||
|
to declare an
|
||
|
.Va execpromise ,
|
||
|
and that is not permitted for setuid or setgid images.
|
||
|
.It Bq Er ENOEXEC
|
||
|
The new process file has the appropriate access
|
||
|
permission, but has an invalid magic number in its header.
|
||
|
.It Bq Er ETXTBSY
|
||
|
The new process file is a pure procedure (shared text)
|
||
|
file that is currently open for writing by some process.
|
||
|
.It Bq Er ENOMEM
|
||
|
The new process requires more virtual memory than
|
||
|
is allowed by the imposed maximum
|
||
|
.Pq Xr getrlimit 2 .
|
||
|
.It Bq Er E2BIG
|
||
|
The number of bytes in the new process's argument list
|
||
|
is larger than the system-imposed limit.
|
||
|
The limit in the system as released is 524288 bytes
|
||
|
.Pq Dv ARG_MAX .
|
||
|
.It Bq Er EFAULT
|
||
|
The new process file is not as long as indicated by
|
||
|
the size values in its header.
|
||
|
.It Bq Er EFAULT
|
||
|
.Fa path ,
|
||
|
.Fa argv ,
|
||
|
or
|
||
|
.Fa envp
|
||
|
point
|
||
|
to an illegal address.
|
||
|
.It Bq Er EINVAL
|
||
|
.Fa argv
|
||
|
did not contain at least one element.
|
||
|
.It Bq Er EIO
|
||
|
An I/O error occurred while reading from the file system.
|
||
|
.It Bq Er ENFILE
|
||
|
During startup of an
|
||
|
.Ar interpreter ,
|
||
|
the system file table was found to be full.
|
||
|
.El
|
||
|
.Sh SEE ALSO
|
||
|
.Xr _exit 2 ,
|
||
|
.Xr fork 2 ,
|
||
|
.Xr execl 3 ,
|
||
|
.Xr exit 3 ,
|
||
|
.Xr elf 5 ,
|
||
|
.Xr environ 7
|
||
|
.Sh STANDARDS
|
||
|
The
|
||
|
.Fn execve
|
||
|
function is expected to conform to
|
||
|
.St -p1003.1-2008 .
|
||
|
.Sh HISTORY
|
||
|
The predecessor of these functions, the former
|
||
|
.Fn exec
|
||
|
system call, first appeared in
|
||
|
.At v1 .
|
||
|
The
|
||
|
.Fn execve
|
||
|
function first appeared in
|
||
|
.At v7 .
|
||
|
.Sh CAVEATS
|
||
|
If a program is
|
||
|
.Em setuid
|
||
|
to a non-superuser, but is executed when the real
|
||
|
.Em uid
|
||
|
is
|
||
|
.Dq root ,
|
||
|
then the process has some of the powers of a superuser as well.
|
||
|
.Pp
|
||
|
.St -p1003.1-2008
|
||
|
permits
|
||
|
.Nm
|
||
|
to leave
|
||
|
.Dv SIGCHLD
|
||
|
as ignored in the new process; portable programs cannot rely on
|
||
|
.Nm
|
||
|
resetting it to the default disposition.
|