tm.3type: tfix
[man-pages.git] / man2 / execveat.2
blob55a6cadb7efbc9489105951b6135631f845f4a9c
1 .\" Copyright (c) 2014 Google, Inc., written by David Drysdale
2 .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH EXECVEAT 2 2021-08-27 "Linux" "Linux Programmer's Manual"
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 .PP
17 .BI "int execveat(int " dirfd ", const char *" pathname ,
18 .BI "             const char *const " argv "[], const char *const " envp [],
19 .BI "             int " flags );
20 .fi
21 .SH DESCRIPTION
22 .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874
23 The
24 .BR execveat ()
25 system call executes the program referred to by the combination of
26 .I dirfd
27 and
28 .IR pathname .
29 It operates in exactly the same way as
30 .BR execve (2),
31 except for the differences described in this manual page.
32 .PP
33 If the pathname given in
34 .I pathname
35 is relative, then it is interpreted relative to the directory
36 referred to by the file descriptor
37 .I dirfd
38 (rather than relative to the current working directory of
39 the calling process, as is done by
40 .BR execve (2)
41 for a relative pathname).
42 .PP
44 .I pathname
45 is relative and
46 .I dirfd
47 is the special value
48 .BR AT_FDCWD ,
49 then
50 .I pathname
51 is interpreted relative to the current working
52 directory of the calling process (like
53 .BR execve (2)).
54 .PP
56 .I pathname
57 is absolute, then
58 .I dirfd
59 is ignored.
60 .PP
62 .I pathname
63 is an empty string and the
64 .B AT_EMPTY_PATH
65 flag is specified, then the file descriptor
66 .I dirfd
67 specifies the file to be executed (i.e.,
68 .I dirfd
69 refers to an executable file, rather than a directory).
70 .PP
71 The
72 .I flags
73 argument is a bit mask that can include zero or more of the following flags:
74 .TP
75 .B AT_EMPTY_PATH
77 .I pathname
78 is an empty string, operate on the file referred to by
79 .I dirfd
80 (which may have been obtained using the
81 .BR open (2)
82 .B O_PATH
83 flag).
84 .TP
85 .B AT_SYMLINK_NOFOLLOW
86 If the file identified by
87 .I dirfd
88 and a non-NULL
89 .I pathname
90 is a symbolic link, then the call fails with the error
91 .BR ELOOP .
92 .SH RETURN VALUE
93 On success,
94 .BR execveat ()
95 does not return.
96 On error, \-1 is returned, and
97 .I errno
98 is set to indicate the error.
99 .SH ERRORS
100 The same errors that occur for
101 .BR execve (2)
102 can also occur for
103 .BR execveat ().
104 The following additional errors can occur for
105 .BR execveat ():
107 .I pathname
108 is relative but
109 .I dirfd
110 is neither
111 .B AT_FDCWD
112 nor a valid file descriptor.
114 .B EINVAL
115 Invalid flag specified in
116 .IR flags .
118 .B ELOOP
119 .I flags
120 includes
121 .B AT_SYMLINK_NOFOLLOW
122 and the file identified by
123 .I dirfd
124 and a non-NULL
125 .I pathname
126 is a symbolic link.
128 .B ENOENT
129 The program identified by
130 .I dirfd
132 .I pathname
133 requires the use of an interpreter program
134 (such as a script starting with "#!"), but the file descriptor
135 .I dirfd
136 was opened with the
137 .B O_CLOEXEC
138 flag, with the result that
139 the program file is inaccessible to the launched interpreter.
140 See BUGS.
142 .B ENOTDIR
143 .I pathname
144 is relative and
145 .I dirfd
146 is a file descriptor referring to a file other than a directory.
147 .SH VERSIONS
148 .BR execveat ()
149 was added to Linux in kernel 3.19.
150 Library support was added to glibc in version 2.34.
151 .SH STANDARDS
153 .BR execveat ()
154 system call is Linux-specific.
155 .SH NOTES
156 In addition to the reasons explained in
157 .BR openat (2),
159 .BR execveat ()
160 system call is also needed to allow
161 .BR fexecve (3)
162 to be implemented on systems that do not have the
163 .I /proc
164 filesystem mounted.
166 When asked to execute a script file, the
167 .I argv[0]
168 that is passed to the script interpreter is a string of the form
169 .I /dev/fd/N
171 .IR /dev/fd/N/P ,
172 where
173 .I N
174 is the number of the file descriptor passed via the
175 .I dirfd
176 argument.
177 A string of the first form occurs when
178 .B AT_EMPTY_PATH
179 is employed.
180 A string of the second form occurs when the script is specified via both
181 .I dirfd
183 .IR pathname ;
184 in this case,
185 .I P
186 is the value given in
187 .IR pathname .
189 For the same reasons described in
190 .BR fexecve (3),
191 the natural idiom when using
192 .BR execveat ()
193 is to set the close-on-exec flag on
194 .IR dirfd .
195 (But see BUGS.)
196 .SH BUGS
198 .B ENOENT
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:
202 .in +4n
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
213 .BR execveat ().
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
219 .SH SEE ALSO
220 .BR execve (2),
221 .BR openat (2),
222 .BR fexecve (3)