]>
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 | .\" |
5722c835 | 25 | .TH FEXECVE 3 2015-07-23 "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> |
37ca7202 | 31 | .sp |
f1440cce | 32 | .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); |
37ca7202 | 33 | .fi |
64642ec9 MK |
34 | .sp |
35 | .in -4n | |
36 | Feature Test Macro Requirements for glibc (see | |
37 | .BR feature_test_macros (7)): | |
38 | .in | |
39 | .sp | |
40 | .BR fexecve (): | |
ea91c3fd MK |
41 | .PD 0 |
42 | .ad l | |
43 | .RS 4 | |
44 | .TP 4 | |
45 | Since glibc 2.10: | |
46 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
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 | |
63 | must be opened read-only, | |
64 | and the caller must have permission to execute the file that it refers to. | |
65 | .\" POSIX.1-2008 specifies the O_EXEC flag for open as an alternative, | |
66 | .\" but Linux doesn't support this flag yet. | |
47297adb | 67 | .SH RETURN VALUE |
37ca7202 MK |
68 | A successful call to |
69 | .BR fexecve () | |
70 | never returns. | |
0dbfbe8e | 71 | On error, the function does return, with a result value of \-1, and |
37ca7202 MK |
72 | .I errno |
73 | is set appropriately. | |
74 | .SH ERRORS | |
c13182ef | 75 | Errors are as for |
37ca7202 MK |
76 | .BR execve (2), |
77 | with the following additions: | |
78 | .TP | |
79 | .B EINVAL | |
80 | .I fd | |
c13182ef | 81 | is not a valid file descriptor, or |
37ca7202 MK |
82 | .I argv |
83 | is NULL, or | |
84 | .I envp | |
85 | is NULL. | |
86 | .TP | |
87 | .B ENOSYS | |
88 | The | |
89 | .I /proc | |
9ee4a2b6 | 90 | filesystem could not be accessed. |
37ca7202 MK |
91 | .SH VERSIONS |
92 | .BR fexecve () | |
93 | is implemented since glibc 2.3.2. | |
0326cdf2 ZL |
94 | .SH ATTRIBUTES |
95 | For an explanation of the terms used in this section, see | |
96 | .BR attributes (7). | |
97 | .TS | |
98 | allbox; | |
99 | lb lb lb | |
100 | l l l. | |
101 | Interface Attribute Value | |
102 | T{ | |
103 | .BR fexecve () | |
104 | T} Thread safety MT-Safe | |
105 | .TE | |
106 | ||
47297adb | 107 | .SH CONFORMING TO |
50e3cb1f MK |
108 | POSIX.1-2008. |
109 | This function is not specified in POSIX.1-2001, | |
110 | and is not widely available on other systems. | |
0397bccf | 111 | It is specified in POSIX.1-2008. |
12c667ca TS |
112 | .SH NOTES |
113 | On Linux, | |
114 | .BR fexecve () | |
115 | is implemented using the | |
116 | .BR proc (5) | |
9ee4a2b6 | 117 | filesystem, so |
12c667ca TS |
118 | .I /proc |
119 | needs to be mounted and available at the time of the call. | |
9dabaedf MK |
120 | .\" FIXME . |
121 | .\" With the addition of the execveat(2), fexecve() can be implemented | |
122 | .\" even where /proc is unavailable. Review future glibc releases to | |
123 | .\" see if the implementation is changed to use execveat(2). | |
36e3fa26 MK |
124 | |
125 | The idea behind | |
126 | .BR fexecve () | |
127 | is to allow the caller to verify (checksum) the contents of | |
128 | an executable before executing it. | |
129 | Simply opening the file, checksumming the contents, and then doing an | |
130 | .BR execve (2) | |
131 | would not suffice, since, between the two steps, the filename, | |
132 | or a directory prefix of the pathname, could have been exchanged | |
133 | (by, for example, modifying the target of a symbolic link). | |
1fb3fb8b | 134 | .BR fexecve () |
36e3fa26 MK |
135 | does not mitigate the problem that the |
136 | .I contents | |
137 | of a file could be changed between the checksumming and the call to | |
138 | .BR fexecve (); | |
139 | for that, the solution is to ensure that the permissions on the file | |
140 | prevent it from being modified by malicious users. | |
67fc42b5 MK |
141 | |
142 | The natural idiom when using | |
143 | .BR fexecve () | |
144 | is to set the close-on-exec flag on | |
145 | .IR fd , | |
146 | so that the file descriptor does not leak through to the program | |
147 | that is executed. | |
148 | This approach is natural for two reasons. | |
149 | First, it prevents file descriptors being consumed unnecessarily. | |
150 | (The executed program normally has no need of a file descriptor | |
151 | that refers to the program itself.) | |
152 | Second, if | |
153 | .BR fexecve () | |
154 | is used recursively, | |
155 | employing the close-on-exec flag prevents the file descriptor exhaustion | |
156 | that would result from the fact that each step in the recursion would | |
157 | cause one more file descriptor to be passed to the new program. | |
9a593da7 MK |
158 | (But see BUGS.) |
159 | .SH BUGS | |
160 | If | |
161 | .I fd | |
162 | refers to a script (i.e., it is an executable text file that names | |
163 | a script interpreter with a first line that begins with the characters | |
164 | .IR #! ) | |
165 | and the close-on-exec flag has been set for | |
166 | .IR fd , | |
167 | then | |
168 | .BR fexecve () | |
169 | fails with the error | |
170 | .BR ENOENT . | |
171 | This error occurs because, | |
172 | by the time the script interpreter is executed, | |
173 | .I fd | |
174 | has already been closed because of the close-on-exec flag. | |
175 | Thus, the close-on-exec flag can't be set on | |
176 | .I fd | |
177 | if it refers to a script, leading to the problems described in NOTES. | |
47297adb | 178 | .SH SEE ALSO |
a940759f MK |
179 | .BR execve (2), |
180 | .BR execveat (2) |