Module Name: src
Committed By: christos
Date: Sun Sep 15 16:55:00 UTC 2019
Modified Files:
src/lib/libc/sys: Makefile.inc execve.2
Log Message:
documentation for fexecve(2)
To generate a diff of this commit:
cvs rdiff -u -r1.240 -r1.241 src/lib/libc/sys/Makefile.inc
cvs rdiff -u -r1.41 -r1.42 src/lib/libc/sys/execve.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/Makefile.inc
diff -u src/lib/libc/sys/Makefile.inc:1.240 src/lib/libc/sys/Makefile.inc:1.241
--- src/lib/libc/sys/Makefile.inc:1.240 Tue Jul 31 09:04:10 2018
+++ src/lib/libc/sys/Makefile.inc Sun Sep 15 12:55:00 2019
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.inc,v 1.240 2018/07/31 13:04:10 rjs Exp $
+# $NetBSD: Makefile.inc,v 1.241 2019/09/15 16:55:00 christos Exp $
# @(#)Makefile.inc 8.3 (Berkeley) 10/24/94
# sys sources
@@ -306,6 +306,7 @@ MLINKS+=extattr_get_file.2 extattr_set_f
MLINKS+=access.2 faccessat.2
MLINKS+=chmod.2 fchmodat.2
MLINKS+=chown.2 fchownat.2
+MLINKS+=execve.2 fexecve.2
MLINKS+=fdiscard.2 posix_fallocate.2
MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatvfs.2 fhopen.2 fhstatvfs1.2
MLINKS+=stat.2 fstatat.2
Index: src/lib/libc/sys/execve.2
diff -u src/lib/libc/sys/execve.2:1.41 src/lib/libc/sys/execve.2:1.42
--- src/lib/libc/sys/execve.2:1.41 Sun May 14 08:30:37 2017
+++ src/lib/libc/sys/execve.2 Sun Sep 15 12:55:00 2019
@@ -1,4 +1,4 @@
-.\" $NetBSD: execve.2,v 1.41 2017/05/14 12:30:37 wiz Exp $
+.\" $NetBSD: execve.2,v 1.42 2019/09/15 16:55:00 christos Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,11 +29,12 @@
.\"
.\" @(#)execve.2 8.5 (Berkeley) 6/1/94
.\"
-.Dd February 24, 2008
+.Dd September 11, 2019
.Dt EXECVE 2
.Os
.Sh NAME
-.Nm execve
+.Nm execve ,
+.Nm fexecve
.Nd execute a file
.Sh LIBRARY
.Lb libc
@@ -41,44 +42,61 @@
.In unistd.h
.Ft int
.Fn execve "const char *path" "char *const argv[]" "char *const envp[]"
+.Ft int
+.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]"
.Sh DESCRIPTION
+The
.Fn execve
+system call
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 .
+The
+.Fn fexecve
+system call is equivalent to
+.Fn execve
+except that the file to be executed is determined by the file
+descriptor
+.Fa fd
+instead of a
+.Fa path .
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
+by the header to be initialized with zero data; see
+.Xr elf 5
+and
.Xr a.out 5 .
.Pp
An interpreter file begins with a line of the form:
.Pp
-.Bd -filled -offset indent -compact
+.Bd -ragged -offset indent -compact
.Sy \&#!
.Em interpreter
.Bq Em arg
.Ed
.Pp
When an interpreter file is
-.Fn execve Ns d
-the system runs the specified
+.Sy execve Ar d ,
+the system actually
+.Sy execve Ap s
+the specified
.Em interpreter .
If the optional
.Em arg
is specified, it becomes the first argument to the
.Em interpreter ,
and the name of the originally
-.Fn execve Ns d
+.Sy execve Ap d
file becomes the second argument;
otherwise, the name of the originally
-.Fn execve Ns d
+.Sy execve Ap d
file becomes the first argument.
The original arguments are shifted over to become the subsequent arguments.
The zeroth argument, normally the name of the
@@ -97,7 +115,8 @@ is a pointer to a null-terminated array
character pointers to null-terminated character strings.
These strings construct the argument list to be made available to the new
process.
-By custom, the first element should be
+At least one 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
@@ -154,6 +173,11 @@ the effective user ID is recorded as the
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-ID bits are not honored if the respective file system has the
+.Cm nosuid
+option enabled or if the new process file is an interpreter file.
+Syscall
+tracing is disabled if effective IDs are changed.
.Pp
The new process also inherits the following attributes from
the calling process:
@@ -176,7 +200,7 @@ the calling process:
.Pp
When a program is executed as a result of an
.Fn execve
-call, it is entered as follows:
+system call, it is entered as follows:
.Bd -literal -offset indent
main(argc, argv, envp)
int argc;
@@ -193,10 +217,32 @@ and
.Fa argv
points to the array of character pointers
to the arguments themselves.
+.Pp
+The
+.Fn fexecve
+ignores the file offset of
+.Fa fd .
+Since execute permission is checked by
+.Fn fexecve ,
+the file descriptor
+.Fa fd
+need not have been opened with the
+.Dv O_EXEC
+flag.
+However, if the file to be executed denies read permission for the process
+preparing to do the exec, the only way to provide the
+.Fa fd
+to
+.Fn fexecve
+is to use the
+.Dv O_EXEC
+flag when opening
+.Fa fd .
+Note that the file to be executed can not be open for writing.
.Sh RETURN VALUES
As the
.Fn execve
-function overlays the current process image
+system call overlays the current process image
with a new process image the successful call
has no process to return to.
If
@@ -206,7 +252,9 @@ return value will be \-1 and the global
.Va errno
is set to indicate the error.
.Sh ERRORS
+The
.Fn execve
+system call
will fail and return to the calling process if:
.Bl -tag -width Er
.It Bq Er E2BIG
@@ -265,23 +313,74 @@ A component of the path prefix is not a
.It Bq Er ETXTBSY
The new process file is a pure procedure (shared text)
file that is currently open for writing or reading by some process.
+.It Bq Er E2BIG
+The number of bytes in the new process' argument list
+is larger than the system-imposed limit.
+This limit is specified by the
+.Xr sysctl 3
+MIB variable
+.Dv KERN_ARGMAX .
+.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
+The
+.Fa path ,
+.Fa argv ,
+or
+.Fa envp
+arguments
+point
+to an illegal address.
+.It Bq Er EIO
+An I/O error occurred while reading from the file system.
+.El
+.Pp
+In addition, the
+.Fn fexecve
+will fail and return to the calling process if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa fd
+argument is not a valid file descriptor open for executing.
.El
.Sh SEE ALSO
.Xr _exit 2 ,
.Xr fork 2 ,
+.Xr open 2 ,
.Xr execl 3 ,
+.Xr exit 3 ,
+.Xr sysctl 3 ,
+.Xr a.out 5 ,
+.Xr elf 5 ,
+.\" .Xr fdescfs 5 ,
.Xr environ 7 ,
.Xr script 7
+.Xr mount 8
.Sh STANDARDS
The
.Fn execve
-function conforms to
-.St -p1003.1-90 .
+system call conforms to
+.St -p1003.1-2001 .
+with the exception of reopening descriptors 0, 1, and/or 2 in certain
+circumstances.
+A future update of the Standard is expected to require this behavior,
+and it may become the default for non-privileged processes as well.
+.\" NB: update this caveat when TC1 is blessed.
+The support for executing interpreted programs is an extension.
+The
+.Fn fexecve
+system call conforms to The Open Group Extended API Set 2 specification.
.Sh HISTORY
The
.Fn execve
function call first appeared in
.At v7 .
+The
+.Fn fexecve
+system call appeared in
+.Nx 10.0 .
.Sh BUGS
If a program is
.Em setuid
@@ -291,3 +390,19 @@ the real
is
.Dq root ,
then the program has some of the powers of a super-user as well.
+.\" .Pp
+.\" When executing an interpreted program through
+.\" .Fn fexecve ,
+.\" kernel supplies
+.\" .Pa /dev/fd/n
+.\" as a second argument to the interpreter,
+.\" where
+.\" .Ar n
+.\" is the file descriptor passed in the
+.\" .Fa fd
+.\" argument to
+.\" .Fn fexecve .
+.\" For this construction to work correctly, the
+.\" .Xr fdescfs 5
+.\" filesystem shall be mounted on
+.\" .Pa /dev/fd .
