Debian Codegraph @

upstream/debian-unstable/man2/close_range.2

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