[src/trunk]: src/lib/libc/sys documentation for fexecve(2)

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/875325fd2fb7
branches:  trunk
changeset: 454384:875325fd2fb7
user:      christos <christos%NetBSD.org@localhost>
date:      Sun Sep 15 16:55:00 2019 +0000

description:
documentation for fexecve(2)

diffstat:

 lib/libc/sys/Makefile.inc |    3 +-
 lib/libc/sys/execve.2     |  143 +++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 131 insertions(+), 15 deletions(-)

diffs (281 lines):

diff -r f7ba0ccc5322 -r 875325fd2fb7 lib/libc/sys/Makefile.inc
--- a/lib/libc/sys/Makefile.inc Sun Sep 15 16:53:58 2019 +0000
+++ b/lib/libc/sys/Makefile.inc Sun Sep 15 16:55:00 2019 +0000
@@ -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+=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
diff -r f7ba0ccc5322 -r 875325fd2fb7 lib/libc/sys/execve.2
--- a/lib/libc/sys/execve.2     Sun Sep 15 16:53:58 2019 +0000
+++ b/lib/libc/sys/execve.2     Sun Sep 15 16:55:00 2019 +0000
@@ -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 @@
 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 @@
 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 @@
 .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 @@
 .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 @@
 .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 @@
 .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 @@
 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 .