man2/close_range.2

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