]>
Commit | Line | Data |
---|---|---|
67fc42b5 | 1 | .\" Copyright (c) 2006, 2014, Michael Kerrisk |
37ca7202 | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
37ca7202 MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
37ca7202 MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
37ca7202 MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
37ca7202 | 24 | .\" |
4b8c67d9 | 25 | .TH FEXECVE 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
37ca7202 MK |
26 | .SH NAME |
27 | fexecve \- execute program specified via file descriptor | |
28 | .SH SYNOPSIS | |
29 | .nf | |
55f49405 | 30 | .B #include <unistd.h> |
68e4db0a | 31 | .PP |
f1440cce | 32 | .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); |
37ca7202 | 33 | .fi |
68e4db0a | 34 | .PP |
64642ec9 MK |
35 | .in -4n |
36 | Feature Test Macro Requirements for glibc (see | |
37 | .BR feature_test_macros (7)): | |
38 | .in | |
68e4db0a | 39 | .PP |
64642ec9 | 40 | .BR fexecve (): |
ea91c3fd MK |
41 | .PD 0 |
42 | .ad l | |
43 | .RS 4 | |
44 | .TP 4 | |
45 | Since glibc 2.10: | |
b0da7b8b | 46 | _POSIX_C_SOURCE\ >=\ 200809L |
ea91c3fd | 47 | .TP |
64642ec9 MK |
48 | Before glibc 2.10: |
49 | _GNU_SOURCE | |
ea91c3fd MK |
50 | .RE |
51 | .ad | |
52 | .PD | |
37ca7202 | 53 | .SH DESCRIPTION |
739b9bb1 | 54 | .BR fexecve () |
c13182ef MK |
55 | performs the same task as |
56 | .BR execve (2), | |
37ca7202 | 57 | with the difference that the file to be executed |
c13182ef | 58 | is specified via a file descriptor, |
37ca7202 MK |
59 | .IR fd , |
60 | rather than via a pathname. | |
afcfe290 MK |
61 | The file descriptor |
62 | .I fd | |
046a1287 MK |
63 | must be opened read-only |
64 | .RB ( O_RDONLY ) | |
65 | or with the | |
66 | .B O_PATH | |
67 | flag | |
afcfe290 | 68 | and the caller must have permission to execute the file that it refers to. |
47297adb | 69 | .SH RETURN VALUE |
37ca7202 MK |
70 | A successful call to |
71 | .BR fexecve () | |
72 | never returns. | |
0dbfbe8e | 73 | On error, the function does return, with a result value of \-1, and |
37ca7202 MK |
74 | .I errno |
75 | is set appropriately. | |
76 | .SH ERRORS | |
c13182ef | 77 | Errors are as for |
37ca7202 MK |
78 | .BR execve (2), |
79 | with the following additions: | |
80 | .TP | |
81 | .B EINVAL | |
82 | .I fd | |
c13182ef | 83 | is not a valid file descriptor, or |
37ca7202 MK |
84 | .I argv |
85 | is NULL, or | |
86 | .I envp | |
87 | is NULL. | |
88 | .TP | |
89 | .B ENOSYS | |
90 | The | |
91 | .I /proc | |
9ee4a2b6 | 92 | filesystem could not be accessed. |
37ca7202 MK |
93 | .SH VERSIONS |
94 | .BR fexecve () | |
95 | is implemented since glibc 2.3.2. | |
0326cdf2 ZL |
96 | .SH ATTRIBUTES |
97 | For an explanation of the terms used in this section, see | |
98 | .BR attributes (7). | |
99 | .TS | |
100 | allbox; | |
101 | lb lb lb | |
102 | l l l. | |
103 | Interface Attribute Value | |
104 | T{ | |
105 | .BR fexecve () | |
106 | T} Thread safety MT-Safe | |
107 | .TE | |
847e0d88 | 108 | .sp 1 |
47297adb | 109 | .SH CONFORMING TO |
50e3cb1f MK |
110 | POSIX.1-2008. |
111 | This function is not specified in POSIX.1-2001, | |
112 | and is not widely available on other systems. | |
0397bccf | 113 | It is specified in POSIX.1-2008. |
12c667ca | 114 | .SH NOTES |
c5511009 | 115 | On Linux with glibc versions 2.26 and earlier, |
12c667ca | 116 | .BR fexecve () |
c5511009 | 117 | is implemented using the |
12c667ca | 118 | .BR proc (5) |
9ee4a2b6 | 119 | filesystem, so |
12c667ca | 120 | .I /proc |
c5511009 | 121 | needs to be mounted and available at the time of the call. |
136baded MK |
122 | Since glibc 2.27, |
123 | .\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60 | |
c5511009 | 124 | if the underlying kernel supports the |
136baded | 125 | .BR execveat (2) |
c5511009 MK |
126 | system call, then |
127 | .BR fexecve () | |
128 | is implemented using that system call, with the benefit that | |
129 | .IR /proc | |
130 | does not need to be mounted. | |
847e0d88 | 131 | .PP |
36e3fa26 MK |
132 | The idea behind |
133 | .BR fexecve () | |
134 | is to allow the caller to verify (checksum) the contents of | |
135 | an executable before executing it. | |
136 | Simply opening the file, checksumming the contents, and then doing an | |
137 | .BR execve (2) | |
138 | would not suffice, since, between the two steps, the filename, | |
139 | or a directory prefix of the pathname, could have been exchanged | |
140 | (by, for example, modifying the target of a symbolic link). | |
1fb3fb8b | 141 | .BR fexecve () |
36e3fa26 MK |
142 | does not mitigate the problem that the |
143 | .I contents | |
144 | of a file could be changed between the checksumming and the call to | |
145 | .BR fexecve (); | |
146 | for that, the solution is to ensure that the permissions on the file | |
147 | prevent it from being modified by malicious users. | |
847e0d88 | 148 | .PP |
67fc42b5 MK |
149 | The natural idiom when using |
150 | .BR fexecve () | |
151 | is to set the close-on-exec flag on | |
152 | .IR fd , | |
153 | so that the file descriptor does not leak through to the program | |
154 | that is executed. | |
155 | This approach is natural for two reasons. | |
156 | First, it prevents file descriptors being consumed unnecessarily. | |
157 | (The executed program normally has no need of a file descriptor | |
158 | that refers to the program itself.) | |
159 | Second, if | |
160 | .BR fexecve () | |
161 | is used recursively, | |
162 | employing the close-on-exec flag prevents the file descriptor exhaustion | |
163 | that would result from the fact that each step in the recursion would | |
164 | cause one more file descriptor to be passed to the new program. | |
9a593da7 MK |
165 | (But see BUGS.) |
166 | .SH BUGS | |
167 | If | |
168 | .I fd | |
169 | refers to a script (i.e., it is an executable text file that names | |
170 | a script interpreter with a first line that begins with the characters | |
171 | .IR #! ) | |
172 | and the close-on-exec flag has been set for | |
173 | .IR fd , | |
174 | then | |
175 | .BR fexecve () | |
176 | fails with the error | |
177 | .BR ENOENT . | |
178 | This error occurs because, | |
179 | by the time the script interpreter is executed, | |
180 | .I fd | |
181 | has already been closed because of the close-on-exec flag. | |
182 | Thus, the close-on-exec flag can't be set on | |
183 | .I fd | |
184 | if it refers to a script, leading to the problems described in NOTES. | |
47297adb | 185 | .SH SEE ALSO |
a940759f MK |
186 | .BR execve (2), |
187 | .BR execveat (2) |