Debian Codegraph @

upstream/debian-trixie/man3/fexecve.3

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