Debian Codegraph @

upstream/debian-unstable/man3/fexecve.3

raw
1 '\" t
2 .\" Copyright 2006-2014, 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 fexecve 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 fexecve \- execute program specified via file descriptor
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []);
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR fexecve ():
26 .nf
27 Since glibc 2.10:
28 _POSIX_C_SOURCE >= 200809L
29 Before glibc 2.10:
30 _GNU_SOURCE
31 .fi
32 .SH DESCRIPTION
33 .BR fexecve ()
34 performs the same task as
35 .BR execve (2),
36 with the difference that the file to be executed
37 is specified via a file descriptor,
38 .IR fd ,
39 rather than via a pathname.
40 The file descriptor
41 .I fd
42 must be opened read-only
43 .RB ( O_RDONLY )
44 or with the
45 .B O_PATH
46 flag
47 and the caller must have permission to execute the file that it refers to.
48 .SH RETURN VALUE
49 A successful call to
50 .BR fexecve ()
51 never returns.
52 On error, the function does return, with a result value of \-1, and
53 .I errno
54 is set to indicate the error.
55 .SH ERRORS
56 Errors are as for
57 .BR execve (2),
58 with the following additions:
59 .TP
60 .B EINVAL
61 .I fd
62 is not a valid file descriptor, or
63 .I argv
64 is NULL, or
65 .I envp
66 is NULL.
67 .TP
68 .B ENOENT
69 The close-on-exec flag is set on
70 .IR fd ,
71 and
72 .I fd
73 refers to a script.
74 See BUGS.
75 .TP
76 .B ENOSYS
77 The kernel does not provide the
78 .BR execveat (2)
79 system call, and the
80 .I /proc
81 filesystem could not be accessed.
82 .SH ATTRIBUTES
83 For an explanation of the terms used in this section, see
84 .BR attributes (7).
85 .TS
86 allbox;
87 lbx lb lb
88 l l l.
89 Interface Attribute Value
90 T{
91 .na
92 .nh
93 .BR fexecve ()
94 T} Thread safety MT-Safe
95 .TE
96 .SH STANDARDS
97 POSIX.1-2008.
98 .SH HISTORY
99 glibc 2.3.2.
100 .P
101 On Linux with glibc versions 2.26 and earlier,
102 .BR fexecve ()
103 is implemented using the
104 .BR proc (5)
105 filesystem, so
106 .I /proc
107 needs to be mounted and available at the time of the call.
108 Since glibc 2.27,
109 .\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60
110 if the underlying kernel supports the
111 .BR execveat (2)
112 system call, then
113 .BR fexecve ()
114 is implemented using that system call, with the benefit that
115 .I /proc
116 does not need to be mounted.
117 .SH NOTES
118 The idea behind
119 .BR fexecve ()
120 is to allow the caller to verify (checksum) the contents of
121 an executable before executing it.
122 Simply opening the file, checksumming the contents, and then doing an
123 .BR execve (2)
124 would not suffice, since, between the two steps, the filename,
125 or a directory prefix of the pathname, could have been exchanged
126 (by, for example, modifying the target of a symbolic link).
127 .BR fexecve ()
128 does not mitigate the problem that the
129 .I contents
130 of a file could be changed between the checksumming and the call to
131 .BR fexecve ();
132 for that, the solution is to ensure that the permissions on the file
133 prevent it from being modified by malicious users.
134 .P
135 The natural idiom when using
136 .BR fexecve ()
137 is to set the close-on-exec flag on
138 .IR fd ,
139 so that the file descriptor does not leak through to the program
140 that is executed.
141 This approach is natural for two reasons.
142 First, it prevents file descriptors being consumed unnecessarily.
143 (The executed program normally has no need of a file descriptor
144 that refers to the program itself.)
145 Second, if
146 .BR fexecve ()
147 is used recursively,
148 employing the close-on-exec flag prevents the file descriptor exhaustion
149 that would result from the fact that each step in the recursion would
150 cause one more file descriptor to be passed to the new program.
151 (But see BUGS.)
152 .SH BUGS
153 If
154 .I fd
155 refers to a script (i.e., it is an executable text file that names
156 a script interpreter with a first line that begins with the characters
157 .IR #! )
158 and the close-on-exec flag has been set for
159 .IR fd ,
160 then
161 .BR fexecve ()
162 fails with the error
163 .BR ENOENT .
164 This error occurs because,
165 by the time the script interpreter is executed,
166 .I fd
167 has already been closed because of the close-on-exec flag.
168 Thus, the close-on-exec flag can't be set on
169 .I fd
170 if it refers to a script, leading to the problems described in NOTES.
171 .SH SEE ALSO
172 .BR execve (2),
173 .BR execveat (2)