Debian Codegraph @

upstream/debian-unstable/man2/execveat.2

raw
1 .\" Copyright 2014, Google, Inc.
2 .\" Copyright 2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH execveat 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 execveat \- execute program relative to a directory file descriptor
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int execveat(int " dirfd ", const char *" path ,
19 .BI " char *const _Nullable " argv [],
20 .BI " char *const _Nullable " envp [],
21 .BI " int " flags );
22 .fi
23 .SH DESCRIPTION
24 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
25 The
26 .BR execveat ()
27 system call executes the program referred to by the combination of
28 .I dirfd
29 and
30 .IR path .
31 It operates in exactly the same way as
32 .BR execve (2),
33 except for the differences described in this manual page.
34 .P
35 If
36 .I path
37 is relative, then it is interpreted relative to the directory
38 referred to by the file descriptor
39 .I dirfd
40 (rather than relative to the current working directory of
41 the calling process, as is done by
42 .BR execve (2)
43 for a relative pathname).
44 .P
45 If
46 .I path
47 is relative and
48 .I dirfd
49 is the special value
50 .BR AT_FDCWD ,
51 then
52 .I path
53 is interpreted relative to the current working
54 directory of the calling process (like
55 .BR execve (2)).
56 .P
57 If
58 .I path
59 is absolute, then
60 .I dirfd
61 is ignored.
62 .P
63 If
64 .I path
65 is an empty string and the
66 .B AT_EMPTY_PATH
67 flag is specified, then the file descriptor
68 .I dirfd
69 specifies the file to be executed (i.e.,
70 .I dirfd
71 refers to an executable file, rather than a directory).
72 .P
73 The
74 .I flags
75 argument is a bit mask that can include zero or more of the following flags:
76 .TP
77 .B AT_EMPTY_PATH
78 If
79 .I path
80 is an empty string, operate on the file referred to by
81 .I dirfd
82 (which may have been obtained using the
83 .BR open (2)
84 .B O_PATH
85 flag).
86 .TP
87 .B AT_SYMLINK_NOFOLLOW
88 If the file identified by
89 .I dirfd
90 and a non-NULL
91 .I path
92 is a symbolic link, then the call fails with the error
93 .BR ELOOP .
94 .SH RETURN VALUE
95 On success,
96 .BR execveat ()
97 does not return.
98 On error, \-1 is returned, and
99 .I errno
100 is set to indicate the error.
101 .SH ERRORS
102 The same errors that occur for
103 .BR execve (2)
104 can also occur for
105 .BR execveat ().
106 The following additional errors can occur for
107 .BR execveat ():
108 .TP
109 .I path
110 is relative but
111 .I dirfd
112 is neither
113 .B AT_FDCWD
114 nor a valid file descriptor.
115 .TP
116 .B EINVAL
117 Invalid flag specified in
118 .IR flags .
119 .TP
120 .B ELOOP
121 .I flags
122 includes
123 .B AT_SYMLINK_NOFOLLOW
124 and the file identified by
125 .I dirfd
126 and a non-NULL
127 .I path
128 is a symbolic link.
129 .TP
130 .B ENOENT
131 The program identified by
132 .I dirfd
133 and
134 .I path
135 requires the use of an interpreter program
136 (such as a script starting with "#!"), but the file descriptor
137 .I dirfd
138 was opened with the
139 .B O_CLOEXEC
140 flag, with the result that
141 the program file is inaccessible to the launched interpreter.
142 See BUGS.
143 .TP
144 .B ENOTDIR
145 .I path
146 is relative and
147 .I dirfd
148 is a file descriptor referring to a file other than a directory.
149 .SH STANDARDS
150 Linux.
151 .SH HISTORY
152 Linux 3.19,
153 glibc 2.34.
154 .SH NOTES
155 In addition to the reasons explained in
156 .BR openat (2),
157 the
158 .BR execveat ()
159 system call is also needed to allow
160 .BR fexecve (3)
161 to be implemented on systems that do not have the
162 .I /proc
163 filesystem mounted.
164 .P
165 When asked to execute a script file, the
166 .I argv[0]
167 that is passed to the script interpreter is a string of the form
168 .I /dev/fd/N
169 or
170 .IR /dev/fd/N/P ,
171 where
172 .I N
173 is the number of the file descriptor passed via the
174 .I dirfd
175 argument.
176 A string of the first form occurs when
177 .B AT_EMPTY_PATH
178 is employed.
179 A string of the second form occurs when the script is specified via both
180 .I dirfd
181 and
182 .IR path ;
183 in this case,
184 .I P
185 is the value given in
186 .IR path .
187 .P
188 For the same reasons described in
189 .BR fexecve (3),
190 the natural idiom when using
191 .BR execveat ()
192 is to set the close-on-exec flag on
193 .IR dirfd .
194 (But see BUGS.)
195 .SH BUGS
196 The
197 .B ENOENT
198 error described above means that it is not possible to set the
199 close-on-exec flag on the file descriptor given to a call of the form:
200 .P
201 .in +4n
202 .EX
203 execveat(fd, "", argv, envp, AT_EMPTY_PATH);
204 .EE
205 .in
206 .P
207 However, the inability to set the close-on-exec flag means that a file
208 descriptor referring to the script leaks through to the script itself.
209 As well as wasting a file descriptor,
210 this leakage can lead to file-descriptor exhaustion in scenarios
211 where scripts recursively employ
212 .BR execveat ().
213 .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML
214 .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229):
215 .\"
216 .\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2
217 .\" Date: Mon, 24 Nov 2014 11:53:59 +0000
218 .SH SEE ALSO
219 .BR execve (2),
220 .BR openat (2),
221 .BR fexecve (3)