Debian Codegraph @

upstream/debian-trixie/man2/execveat.2

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