1 .\" Copyright (c) 2014 Google, Inc., written by David Drysdale
2 .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .TH EXECVEAT 2 2021-08-27 "Linux" "Linux Programmer's Manual"
8 execveat \- execute program relative to a directory file descriptor
11 .RI ( libc ", " \-lc )
14 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
15 .B #include <unistd.h>
17 .BI "int execveat(int " dirfd ", const char *" pathname ,
18 .BI " const char *const " argv "[], const char *const " envp [],
22 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
25 system call executes the program referred to by the combination of
29 It operates in exactly the same way as
31 except for the differences described in this manual page.
33 If the pathname given in
35 is relative, then it is interpreted relative to the directory
36 referred to by the file descriptor
38 (rather than relative to the current working directory of
39 the calling process, as is done by
41 for a relative pathname).
51 is interpreted relative to the current working
52 directory of the calling process (like
63 is an empty string and the
65 flag is specified, then the file descriptor
67 specifies the file to be executed (i.e.,
69 refers to an executable file, rather than a directory).
73 argument is a bit mask that can include zero or more of the following flags:
78 is an empty string, operate on the file referred to by
80 (which may have been obtained using the
85 .B AT_SYMLINK_NOFOLLOW
86 If the file identified by
90 is a symbolic link, then the call fails with the error
96 On error, \-1 is returned, and
98 is set to indicate the error.
100 The same errors that occur for
104 The following additional errors can occur for
112 nor a valid file descriptor.
115 Invalid flag specified in
121 .B AT_SYMLINK_NOFOLLOW
122 and the file identified by
129 The program identified by
133 requires the use of an interpreter program
134 (such as a script starting with "#!"), but the file descriptor
138 flag, with the result that
139 the program file is inaccessible to the launched interpreter.
146 is a file descriptor referring to a file other than a directory.
149 was added to Linux in kernel 3.19.
150 Library support was added to glibc in version 2.34.
154 system call is Linux-specific.
156 In addition to the reasons explained in
160 system call is also needed to allow
162 to be implemented on systems that do not have the
166 When asked to execute a script file, the
168 that is passed to the script interpreter is a string of the form
174 is the number of the file descriptor passed via the
177 A string of the first form occurs when
180 A string of the second form occurs when the script is specified via both
186 is the value given in
189 For the same reasons described in
191 the natural idiom when using
193 is to set the close-on-exec flag on
199 error described above means that it is not possible to set the
200 close-on-exec flag on the file descriptor given to a call of the form:
204 execveat(fd, "", argv, envp, AT_EMPTY_PATH);
208 However, the inability to set the close-on-exec flag means that a file
209 descriptor referring to the script leaks through to the script itself.
210 As well as wasting a file descriptor,
211 this leakage can lead to file-descriptor exhaustion in scenarios
212 where scripts recursively employ
214 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
215 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
217 .\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2
218 .\" Date: Mon, 24 Nov 2014 11:53:59 +0000