| .\" Copyright (c) 2014 Google, Inc., written by David Drysdale |
| .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH EXECVEAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| execveat \- execute program relative to a directory file descriptor |
| .SH SYNOPSIS |
| .B #include <unistd.h> |
| .PP |
| .BI "int execveat(int " dirfd ", const char *" pathname "," |
| .br |
| .BI " char *const " argv "[], char *const " envp "[]," |
| .br |
| .BI " int " flags ); |
| .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. |
| .PP |
| 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). |
| .PP |
| 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)). |
| .PP |
| If |
| .I pathname |
| is absolute, then |
| .I dirfd |
| is ignored. |
| .PP |
| If |
| .I pathname |
| is an empty string and the |
| .BR AT_EMPTY_PATH |
| flag is specified, then the file descriptor |
| .I dirfd |
| specifies the file to be executed (i.e., |
| .IR dirfd |
| refers to an executable file, rather than a directory). |
| .PP |
| The |
| .I flags |
| argument is a bit mask that can include zero or more of the following flags: |
| .TP |
| .BR AT_EMPTY_PATH |
| If |
| .I pathname |
| is an empty string, operate on the file referred to by |
| .IR 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 appropriately. |
| .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 |
| .B EBADF |
| .I dirfd |
| is not a valid file descriptor. |
| .TP |
| .B EINVAL |
| Invalid flag specified in |
| .IR flags . |
| .TP |
| .B ELOOP |
| .I flags |
| includes |
| .BR 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 VERSIONS |
| .BR execveat () |
| was added to Linux in kernel 3.19. |
| GNU C library support is pending. |
| .\" FIXME . check for glibc support in a future release |
| .SH CONFORMING TO |
| The |
| .BR execveat () |
| system call is Linux-specific. |
| .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. |
| .PP |
| When asked to execute a script file, the |
| .IR argv[0] |
| that is passed to the script interpreter is a string of the form |
| .IR /dev/fd/N |
| or |
| .IR /dev/fd/N/P , |
| where |
| .I N |
| is the number of the file descriptor passed via the |
| .IR dirfd |
| argument. |
| A string of the first form occurs when |
| .BR AT_EMPTY_PATH |
| is employed. |
| A string of the second form occurs when the script is specified via both |
| .IR dirfd |
| and |
| .IR pathname ; |
| in this case, |
| .IR P |
| is the value given in |
| .IR pathname . |
| .PP |
| 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: |
| .PP |
| execveat(fd, "", argv, envp, AT_EMPTY_PATH); |
| .PP |
| 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) |