Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 220 insertions, 0 deletions

diff --git a/man/man2/execveat.2 b/man/man2/execveat.2
new file mode 100644
index 0000000..279a824
--- /dev/null
+++ b/man/man2/execveat.2
@@ -0,0 +1,220 @@
+.\" Copyright (c) 2014 Google, Inc., written by David Drysdale
+.\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH execveat 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+execveat \- execute program relative to a directory file descriptor
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int execveat(int " dirfd ", const char *" pathname ,
+.BI "             char *const _Nullable " argv [],
+.BI "             char *const _Nullable " envp [],
+.BI "             int " flags );
+.fi
+.SH DESCRIPTION
+.\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
+The
+.BR execveat ()
+system call executes the program referred to by the combination of
+.I dirfd
+and
+.IR pathname .
+It operates in exactly the same way as
+.BR execve (2),
+except for the differences described in this manual page.
+.P
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR execve (2)
+for a relative pathname).
+.P
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR execve (2)).
+.P
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+.P
+If
+.I pathname
+is an empty string and the
+.B AT_EMPTY_PATH
+flag is specified, then the file descriptor
+.I dirfd
+specifies the file to be executed (i.e.,
+.I dirfd
+refers to an executable file, rather than a directory).
+.P
+The
+.I flags
+argument is a bit mask that can include zero or more of the following flags:
+.TP
+.B AT_EMPTY_PATH
+If
+.I pathname
+is an empty string, operate on the file referred to by
+.I dirfd
+(which may have been obtained using the
+.BR open (2)
+.B O_PATH
+flag).
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If the file identified by
+.I dirfd
+and a non-NULL
+.I pathname
+is a symbolic link, then the call fails with the error
+.BR ELOOP .
+.SH RETURN VALUE
+On success,
+.BR execveat ()
+does not return.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+The same errors that occur for
+.BR execve (2)
+can also occur for
+.BR execveat ().
+The following additional errors can occur for
+.BR execveat ():
+.TP
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ELOOP
+.I flags
+includes
+.B AT_SYMLINK_NOFOLLOW
+and the file identified by
+.I dirfd
+and a non-NULL
+.I pathname
+is a symbolic link.
+.TP
+.B ENOENT
+The program identified by
+.I dirfd
+and
+.I pathname
+requires the use of an interpreter program
+(such as a script starting with "#!"), but the file descriptor
+.I dirfd
+was opened with the
+.B O_CLOEXEC
+flag, with the result that
+the program file is inaccessible to the launched interpreter.
+See BUGS.
+.TP
+.B ENOTDIR
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 3.19,
+glibc 2.34.
+.SH NOTES
+In addition to the reasons explained in
+.BR openat (2),
+the
+.BR execveat ()
+system call is also needed to allow
+.BR fexecve (3)
+to be implemented on systems that do not have the
+.I /proc
+filesystem mounted.
+.P
+When asked to execute a script file, the
+.I argv[0]
+that is passed to the script interpreter is a string of the form
+.I /dev/fd/N
+or
+.IR /dev/fd/N/P ,
+where
+.I N
+is the number of the file descriptor passed via the
+.I dirfd
+argument.
+A string of the first form occurs when
+.B AT_EMPTY_PATH
+is employed.
+A string of the second form occurs when the script is specified via both
+.I dirfd
+and
+.IR pathname ;
+in this case,
+.I P
+is the value given in
+.IR pathname .
+.P
+For the same reasons described in
+.BR fexecve (3),
+the natural idiom when using
+.BR execveat ()
+is to set the close-on-exec flag on
+.IR dirfd .
+(But see BUGS.)
+.SH BUGS
+The
+.B ENOENT
+error described above means that it is not possible to set the
+close-on-exec flag on the file descriptor given to a call of the form:
+.P
+.in +4n
+.EX
+execveat(fd, "", argv, envp, AT_EMPTY_PATH);
+.EE
+.in
+.P
+However, the inability to set the close-on-exec flag means that a file
+descriptor referring to the script leaks through to the script itself.
+As well as wasting a file descriptor,
+this leakage can lead to file-descriptor exhaustion in scenarios
+where scripts recursively employ
+.BR execveat ().
+.\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
+.\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
+.\"
+.\"     Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\"                        for execveat(2
+.\"     Date: Mon, 24 Nov 2014 11:53:59 +0000
+.SH SEE ALSO
+.BR execve (2),
+.BR openat (2),
+.BR fexecve (3)