Debian Codegraph @

upstream/debian-trixie/man2/close_range.2

raw
1 .\" Copyright (c) 2020 Stephen Kitt <[email protected]>
2 .\" and Copyright (c) 2021 Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH close_range 2 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 close_range \- close all file descriptors in a given range
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ", " \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <unistd.h>
16 .P
17 .BR "#include <linux/close_range.h>" " /* Definition of " CLOSE_RANGE_*
18 .BR "" " constants */"
19 .P
20 .BI "int close_range(unsigned int " first ", unsigned int " last \
21 ", int " flags );
22 .fi
23 .SH DESCRIPTION
24 The
25 .BR close_range ()
26 system call closes all open file descriptors from
27 .I first
28 to
29 .I last
30 (included).
31 .P
32 Errors closing a given file descriptor are currently ignored.
33 .P
34 .I flags
35 is a bit mask containing 0 or more of the following:
36 .TP
37 .BR CLOSE_RANGE_CLOEXEC " (since Linux 5.11)"
38 Set the close-on-exec flag on the specified file descriptors,
39 rather than immediately closing them.
40 .TP
41 .B CLOSE_RANGE_UNSHARE
42 Unshare the specified file descriptors from any other processes
43 before closing them,
44 avoiding races with other threads sharing the file descriptor table.
45 .SH RETURN VALUE
46 On success,
47 .BR close_range ()
48 returns 0.
49 On error, \-1 is returned and
50 .I errno
51 is set to indicate the error.
52 .SH ERRORS
53 .TP
54 .B EINVAL
55 .I flags
56 is not valid, or
57 .I first
58 is greater than
59 .IR last .
60 .P
61 The following can occur with
62 .B CLOSE_RANGE_UNSHARE
63 (when constructing the new descriptor table):
64 .TP
65 .B EMFILE
66 The number of open file descriptors exceeds the limit specified in
67 .I /proc/sys/fs/nr_open
68 (see
69 .BR proc (5)).
70 This error can occur in situations where that limit was lowered before
71 a call to
72 .BR close_range ()
73 where the
74 .B CLOSE_RANGE_UNSHARE
75 flag is specified.
76 .TP
77 .B ENOMEM
78 Insufficient kernel memory was available.
79 .SH STANDARDS
80 None.
81 .SH HISTORY
82 FreeBSD.
83 Linux 5.9,
84 glibc 2.34.
85 .SH NOTES
86 .SS Closing all open file descriptors
87 .\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de
88 To avoid blindly closing file descriptors
89 in the range of possible file descriptors,
90 this is sometimes implemented (on Linux)
91 by listing open file descriptors in
92 .I /proc/self/fd/
93 and calling
94 .BR close (2)
95 on each one.
96 .BR close_range ()
97 can take care of this without requiring
98 .I /proc
99 and within a single system call,
100 which provides significant performance benefits.
101 .SS Closing file descriptors before exec
102 .\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8
103 File descriptors can be closed safely using
104 .P
105 .in +4n
106 .EX
107 /* we don't want anything past stderr here */
108 close_range(3, \[ti]0U, CLOSE_RANGE_UNSHARE);
109 execve(....);
110 .EE
111 .in
112 .P
113 .B CLOSE_RANGE_UNSHARE
114 is conceptually equivalent to
115 .P
116 .in +4n
117 .EX
118 unshare(CLONE_FILES);
119 close_range(first, last, 0);
120 .EE
121 .in
122 .P
123 but can be more efficient:
124 if the unshared range extends past
125 the current maximum number of file descriptors allocated
126 in the caller's file descriptor table
127 (the common case when
128 .I last
129 is \[ti]0U),
130 the kernel will unshare a new file descriptor table for the caller up to
131 .IR first ,
132 copying as few file descriptors as possible.
133 This avoids subsequent
134 .BR close (2)
135 calls entirely;
136 the whole operation is complete once the table is unshared.
137 .SS Closing files on \fBexec\fP
138 .\" 582f1fb6b721facf04848d2ca57f34468da1813e
139 This is particularly useful in cases where multiple
140 .RB pre- exec
141 setup steps risk conflicting with each other.
142 For example, setting up a
143 .BR seccomp (2)
144 profile can conflict with a
145 .BR close_range ()
146 call:
147 if the file descriptors are closed before the
148 .BR seccomp (2)
149 profile is set up,
150 the profile setup can't use them itself,
151 or control their closure;
152 if the file descriptors are closed afterwards,
153 the seccomp profile can't block the
154 .BR close_range ()
155 call or any fallbacks.
156 Using
157 .B CLOSE_RANGE_CLOEXEC
158 avoids this:
159 the descriptors can be marked before the
160 .BR seccomp (2)
161 profile is set up,
162 and the profile can control access to
163 .BR close_range ()
164 without affecting the calling process.
165 .SH EXAMPLES
166 The program shown below opens the files named in its command-line arguments,
167 displays the list of files that it has opened
168 (by iterating through the entries in
169 .IR /proc/PID/fd ),
170 uses
171 .BR close_range ()
172 to close all file descriptors greater than or equal to 3,
173 and then once more displays the process's list of open files.
174 The following example demonstrates the use of the program:
175 .P
176 .in +4n
177 .EX
178 $ \fBtouch /tmp/a /tmp/b /tmp/c\fP
179 $ \fB./a.out /tmp/a /tmp/b /tmp/c\fP
180 /tmp/a opened as FD 3
181 /tmp/b opened as FD 4
182 /tmp/c opened as FD 5
183 /proc/self/fd/0 ==> /dev/pts/1
184 /proc/self/fd/1 ==> /dev/pts/1
185 /proc/self/fd/2 ==> /dev/pts/1
186 /proc/self/fd/3 ==> /tmp/a
187 /proc/self/fd/4 ==> /tmp/b
188 /proc/self/fd/5 ==> /tmp/b
189 /proc/self/fd/6 ==> /proc/9005/fd
190 ========= About to call close_range() =======
191 /proc/self/fd/0 ==> /dev/pts/1
192 /proc/self/fd/1 ==> /dev/pts/1
193 /proc/self/fd/2 ==> /dev/pts/1
194 /proc/self/fd/3 ==> /proc/9005/fd
195 .EE
196 .in
197 .P
198 Note that the lines showing the pathname
199 .I /proc/9005/fd
200 result from the calls to
201 .BR opendir (3).
202 .SS Program source
203 \&
204 .\" SRC BEGIN (close_range.c)
205 .EX
206 #define _GNU_SOURCE
207 #include <dirent.h>
208 #include <fcntl.h>
209 #include <limits.h>
210 #include <stdio.h>
211 #include <stdlib.h>
212 #include <sys/types.h>
213 #include <unistd.h>
214 \&
215 /* Show the contents of the symbolic links in /proc/self/fd */
216 \&
217 static void
218 show_fds(void)
219 {
220 DIR *dirp;
221 char path[PATH_MAX], target[PATH_MAX];
222 ssize_t len;
223 struct dirent *dp;
224 \&
225 dirp = opendir("/proc/self/fd");
226 if (dirp == NULL) {
227 perror("opendir");
228 exit(EXIT_FAILURE);
229 }
230 \&
231 for (;;) {
232 dp = readdir(dirp);
233 if (dp == NULL)
234 break;
235 \&
236 if (dp\->d_type == DT_LNK) {
237 snprintf(path, sizeof(path), "/proc/self/fd/%s",
238 dp\->d_name);
239 \&
240 len = readlink(path, target, sizeof(target));
241 printf("%s ==> %.*s\[rs]n", path, (int) len, target);
242 }
243 }
244 \&
245 closedir(dirp);
246 }
247 \&
248 int
249 main(int argc, char *argv[])
250 {
251 int fd;
252 \&
253 for (size_t j = 1; j < argc; j++) {
254 fd = open(argv[j], O_RDONLY);
255 if (fd == \-1) {
256 perror(argv[j]);
257 exit(EXIT_FAILURE);
258 }
259 printf("%s opened as FD %d\[rs]n", argv[j], fd);
260 }
261 \&
262 show_fds();
263 \&
264 printf("========= About to call close_range() =======\[rs]n");
265 \&
266 if (close_range(3, \[ti]0U, 0) == \-1) {
267 perror("close_range");
268 exit(EXIT_FAILURE);
269 }
270 \&
271 show_fds();
272 exit(EXIT_FAILURE);
273 }
274 .EE
275 .\" SRC END
276 .SH SEE ALSO
277 .BR close (2)