diff options
Diffstat (limited to 'man/man2/execveat.2')
| -rw-r--r-- | man/man2/execveat.2 | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/man/man2/execveat.2 b/man/man2/execveat.2 new file mode 100644 index 000000000..ff0eb278f --- /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 (date) "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) |