]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
67fc42b5 | 2 | .\" Copyright (c) 2006, 2014, Michael Kerrisk |
37ca7202 | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
37ca7202 | 5 | .\" |
4c1c5274 | 6 | .TH fexecve 3 (date) "Linux man-pages (unreleased)" |
37ca7202 MK |
7 | .SH NAME |
8 | fexecve \- execute program specified via file descriptor | |
afa8db94 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
11 | .RI ( libc ", " \-lc ) | |
37ca7202 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
55f49405 | 14 | .B #include <unistd.h> |
68e4db0a | 15 | .PP |
f1440cce | 16 | .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); |
37ca7202 | 17 | .fi |
68e4db0a | 18 | .PP |
d39ad78f | 19 | .RS -4 |
64642ec9 MK |
20 | Feature Test Macro Requirements for glibc (see |
21 | .BR feature_test_macros (7)): | |
d39ad78f | 22 | .RE |
68e4db0a | 23 | .PP |
64642ec9 | 24 | .BR fexecve (): |
9d2adbae MK |
25 | .nf |
26 | Since glibc 2.10: | |
5c10d2c5 | 27 | _POSIX_C_SOURCE >= 200809L |
9d2adbae MK |
28 | Before glibc 2.10: |
29 | _GNU_SOURCE | |
30 | .fi | |
37ca7202 | 31 | .SH DESCRIPTION |
739b9bb1 | 32 | .BR fexecve () |
c13182ef MK |
33 | performs the same task as |
34 | .BR execve (2), | |
37ca7202 | 35 | with the difference that the file to be executed |
c13182ef | 36 | is specified via a file descriptor, |
37ca7202 MK |
37 | .IR fd , |
38 | rather than via a pathname. | |
afcfe290 MK |
39 | The file descriptor |
40 | .I fd | |
046a1287 MK |
41 | must be opened read-only |
42 | .RB ( O_RDONLY ) | |
43 | or with the | |
44 | .B O_PATH | |
45 | flag | |
afcfe290 | 46 | and the caller must have permission to execute the file that it refers to. |
47297adb | 47 | .SH RETURN VALUE |
37ca7202 MK |
48 | A successful call to |
49 | .BR fexecve () | |
50 | never returns. | |
0dbfbe8e | 51 | On error, the function does return, with a result value of \-1, and |
37ca7202 | 52 | .I errno |
f6a4078b | 53 | is set to indicate the error. |
37ca7202 | 54 | .SH ERRORS |
c13182ef | 55 | Errors are as for |
37ca7202 MK |
56 | .BR execve (2), |
57 | with the following additions: | |
58 | .TP | |
59 | .B EINVAL | |
60 | .I fd | |
c13182ef | 61 | is not a valid file descriptor, or |
37ca7202 MK |
62 | .I argv |
63 | is NULL, or | |
64 | .I envp | |
65 | is NULL. | |
66 | .TP | |
5a7f305a MK |
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 | |
37ca7202 | 75 | .B ENOSYS |
56b242b1 MK |
76 | The kernel does not provide the |
77 | .BR execveat (2) | |
78 | system call, and the | |
37ca7202 | 79 | .I /proc |
9ee4a2b6 | 80 | filesystem could not be accessed. |
0326cdf2 ZL |
81 | .SH ATTRIBUTES |
82 | For an explanation of the terms used in this section, see | |
83 | .BR attributes (7). | |
84 | .TS | |
85 | allbox; | |
c466875e | 86 | lbx lb lb |
0326cdf2 ZL |
87 | l l l. |
88 | Interface Attribute Value | |
89 | T{ | |
9e54434e BR |
90 | .na |
91 | .nh | |
0326cdf2 ZL |
92 | .BR fexecve () |
93 | T} Thread safety MT-Safe | |
94 | .TE | |
847e0d88 | 95 | .sp 1 |
3113c7f3 | 96 | .SH STANDARDS |
50e3cb1f | 97 | POSIX.1-2008. |
4131356c AC |
98 | .SH HISTORY |
99 | glibc 2.3.2. | |
100 | .PP | |
c5511009 | 101 | On Linux with glibc versions 2.26 and earlier, |
12c667ca | 102 | .BR fexecve () |
c5511009 | 103 | is implemented using the |
12c667ca | 104 | .BR proc (5) |
9ee4a2b6 | 105 | filesystem, so |
12c667ca | 106 | .I /proc |
c5511009 | 107 | needs to be mounted and available at the time of the call. |
136baded MK |
108 | Since glibc 2.27, |
109 | .\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60 | |
c5511009 | 110 | if the underlying kernel supports the |
136baded | 111 | .BR execveat (2) |
c5511009 MK |
112 | system call, then |
113 | .BR fexecve () | |
114 | is implemented using that system call, with the benefit that | |
1ae6b2c7 | 115 | .I /proc |
c5511009 | 116 | does not need to be mounted. |
4131356c | 117 | .SH NOTES |
36e3fa26 MK |
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). | |
1fb3fb8b | 127 | .BR fexecve () |
36e3fa26 MK |
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. | |
847e0d88 | 134 | .PP |
67fc42b5 MK |
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. | |
9a593da7 MK |
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. | |
47297adb | 171 | .SH SEE ALSO |
a940759f MK |
172 | .BR execve (2), |
173 | .BR execveat (2) |