| blob | d11907bdd10c33645b0097e24f08d6f5bbae739a |
1 .\" Copyright (c) 2014 Google, Inc., written by David Drysdale
2 .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .TH EXECVEAT 2 2021-08-27 "Linux" "Linux Programmer's Manual"
27 .SH NAME
28 execveat \- execute program relative to a directory file descriptor
29 .SH SYNOPSIS
30 .nf
31 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
32 .B #include <unistd.h>
33 .PP
34 .BI "int execveat(int " dirfd ", const char *" pathname ,
35 .BI " const char *const " argv "[], const char *const " envp [],
36 .BI " int " flags );
37 .fi
38 .SH DESCRIPTION
39 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
40 The
41 .BR execveat ()
42 system call executes the program referred to by the combination of
43 .I dirfd
44 and
45 .IR pathname .
46 It operates in exactly the same way as
47 .BR execve (2),
48 except for the differences described in this manual page.
49 .PP
50 If the pathname given in
51 .I pathname
52 is relative, then it is interpreted relative to the directory
53 referred to by the file descriptor
54 .I dirfd
55 (rather than relative to the current working directory of
56 the calling process, as is done by
57 .BR execve (2)
58 for a relative pathname).
59 .PP
60 If
61 .I pathname
62 is relative and
63 .I dirfd
64 is the special value
65 .BR AT_FDCWD ,
66 then
67 .I pathname
68 is interpreted relative to the current working
69 directory of the calling process (like
70 .BR execve (2)).
71 .PP
72 If
73 .I pathname
74 is absolute, then
75 .I dirfd
76 is ignored.
77 .PP
78 If
79 .I pathname
80 is an empty string and the
81 .BR AT_EMPTY_PATH
82 flag is specified, then the file descriptor
83 .I dirfd
84 specifies the file to be executed (i.e.,
85 .IR dirfd
86 refers to an executable file, rather than a directory).
87 .PP
88 The
89 .I flags
90 argument is a bit mask that can include zero or more of the following flags:
91 .TP
92 .BR AT_EMPTY_PATH
93 If
94 .I pathname
95 is an empty string, operate on the file referred to by
96 .IR dirfd
97 (which may have been obtained using the
98 .BR open (2)
99 .B O_PATH
100 flag).
101 .TP
102 .B AT_SYMLINK_NOFOLLOW
103 If the file identified by
104 .I dirfd
105 and a non-NULL
106 .I pathname
107 is a symbolic link, then the call fails with the error
108 .BR ELOOP .
109 .SH RETURN VALUE
110 On success,
111 .BR execveat ()
112 does not return.
113 On error, \-1 is returned, and
114 .I errno
115 is set to indicate the error.
116 .SH ERRORS
117 The same errors that occur for
118 .BR execve (2)
119 can also occur for
120 .BR execveat ().
121 The following additional errors can occur for
122 .BR execveat ():
123 .TP
124 .I pathname
125 is relative but
126 .I dirfd
127 is neither
128 .B AT_FDCWD
129 nor a valid file descriptor.
130 .TP
131 .B EINVAL
132 Invalid flag specified in
133 .IR flags .
134 .TP
135 .B ELOOP
136 .I flags
137 includes
138 .BR AT_SYMLINK_NOFOLLOW
139 and the file identified by
140 .I dirfd
141 and a non-NULL
142 .I pathname
143 is a symbolic link.
144 .TP
145 .B ENOENT
146 The program identified by
147 .I dirfd
148 and
149 .I pathname
150 requires the use of an interpreter program
151 (such as a script starting with "#!"), but the file descriptor
152 .I dirfd
153 was opened with the
154 .B O_CLOEXEC
155 flag, with the result that
156 the program file is inaccessible to the launched interpreter.
157 See BUGS.
158 .TP
159 .B ENOTDIR
160 .I pathname
161 is relative and
162 .I dirfd
163 is a file descriptor referring to a file other than a directory.
164 .SH VERSIONS
165 .BR execveat ()
166 was added to Linux in kernel 3.19.
167 Library support was added to glibc in version 2.34.
168 .SH CONFORMING TO
169 The
170 .BR execveat ()
171 system call is Linux-specific.
172 .SH NOTES
173 In addition to the reasons explained in
174 .BR openat (2),
175 the
176 .BR execveat ()
177 system call is also needed to allow
178 .BR fexecve (3)
179 to be implemented on systems that do not have the
180 .I /proc
181 filesystem mounted.
182 .PP
183 When asked to execute a script file, the
184 .IR argv[0]
185 that is passed to the script interpreter is a string of the form
186 .IR /dev/fd/N
187 or
188 .IR /dev/fd/N/P ,
189 where
190 .I N
191 is the number of the file descriptor passed via the
192 .IR dirfd
193 argument.
194 A string of the first form occurs when
195 .BR AT_EMPTY_PATH
196 is employed.
197 A string of the second form occurs when the script is specified via both
198 .IR dirfd
199 and
200 .IR pathname ;
201 in this case,
202 .IR P
203 is the value given in
204 .IR pathname .
205 .PP
206 For the same reasons described in
207 .BR fexecve (3),
208 the natural idiom when using
209 .BR execveat ()
210 is to set the close-on-exec flag on
211 .IR dirfd .
212 (But see BUGS.)
213 .SH BUGS
214 The
215 .B ENOENT
216 error described above means that it is not possible to set the
217 close-on-exec flag on the file descriptor given to a call of the form:
218 .PP
219 execveat(fd, "", argv, envp, AT_EMPTY_PATH);
220 .PP
221 However, the inability to set the close-on-exec flag means that a file
222 descriptor referring to the script leaks through to the script itself.
223 As well as wasting a file descriptor,
224 this leakage can lead to file-descriptor exhaustion in scenarios
225 where scripts recursively employ
226 .BR execveat ().
227 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
228 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
229 .\"
230 .\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2
231 .\" Date: Mon, 24 Nov 2014 11:53:59 +0000
232 .SH SEE ALSO
233 .BR execve (2),
234 .BR openat (2),
235 .BR fexecve (3)