close_range(2) System Calls Manual close_range(2)
NAME
close_range - close all file descriptors in a given range
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <linux/close_range.h>
int close_range(unsigned int first, unsigned int last,
unsigned int flags);
DESCRIPTION
The close_range() system call closes all open file descriptors from
first to last (included).
Errors closing a given file descriptor are currently ignored.
flags is a bit mask containing 0 or more of the following:
CLOSE_RANGE_CLOEXEC (since Linux 5.11)
Set the close-on-exec flag on the specified file descriptors,
rather than immediately closing them.
CLOSE_RANGE_UNSHARE
Unshare the specified file descriptors from any other processes
before closing them, avoiding races with other threads sharing
the file descriptor table.
RETURN VALUE
On success, close_range() returns 0. On error, -1 is returned and er-
rno is set to indicate the error.
ERRORS
EINVAL flags is not valid, or first is greater than last.
The following can occur with CLOSE_RANGE_UNSHARE (when constructing the
new descriptor table):
EMFILE The number of open file descriptors exceeds the limit specified
in /proc/sys/fs/nr_open (see proc(5)). This error can occur in
situations where that limit was lowered before a call to
close_range() where the CLOSE_RANGE_UNSHARE flag is specified.
ENOMEM Insufficient kernel memory was available.
VERSIONS
close_range() first appeared in Linux 5.9. Library support was added
in glibc 2.34.
STANDARDS
close_range() is a nonstandard function that is also present on Free-
BSD.
NOTES
Closing all open file descriptors
To avoid blindly closing file descriptors in the range of possible file
descriptors, this is sometimes implemented (on Linux) by listing open
file descriptors in /proc/self/fd/ and calling close(2) on each one.
close_range() can take care of this without requiring /proc and within
a single system call, which provides significant performance benefits.
Closing file descriptors before exec
File descriptors can be closed safely using
/* we don't want anything past stderr here */
close_range(3, ~0U, CLOSE_RANGE_UNSHARE);
execve(....);
CLOSE_RANGE_UNSHARE is conceptually equivalent to
unshare(CLONE_FILES);
close_range(first, last, 0);
but can be more efficient: if the unshared range extends past the cur-
rent maximum number of file descriptors allocated in the caller's file
descriptor table (the common case when last is ~0U), the kernel will
unshare a new file descriptor table for the caller up to first, copying
as few file descriptors as possible. This avoids subsequent close(2)
calls entirely; the whole operation is complete once the table is un-
shared.
Closing files on exec
This is particularly useful in cases where multiple pre-exec setup
steps risk conflicting with each other. For example, setting up a sec-
comp(2) profile can conflict with a close_range() call: if the file de-
scriptors are closed before the seccomp(2) profile is set up, the pro-
file setup can't use them itself, or control their closure; if the file
descriptors are closed afterwards, the seccomp profile can't block the
close_range() call or any fallbacks. Using CLOSE_RANGE_CLOEXEC avoids
this: the descriptors can be marked before the seccomp(2) profile is
set up, and the profile can control access to close_range() without af-
fecting the calling process.
EXAMPLES
The program shown below opens the files named in its command-line argu-
ments, displays the list of files that it has opened (by iterating
through the entries in /proc/PID/fd), uses close_range() to close all
file descriptors greater than or equal to 3, and then once more dis-
plays the process's list of open files. The following example demon-
strates the use of the program:
$ touch /tmp/a /tmp/b /tmp/c
$ ./a.out /tmp/a /tmp/b /tmp/c
/tmp/a opened as FD 3
/tmp/b opened as FD 4
/tmp/c opened as FD 5
/proc/self/fd/0 ==> /dev/pts/1
/proc/self/fd/1 ==> /dev/pts/1
/proc/self/fd/2 ==> /dev/pts/1
/proc/self/fd/3 ==> /tmp/a
/proc/self/fd/4 ==> /tmp/b
/proc/self/fd/5 ==> /tmp/b
/proc/self/fd/6 ==> /proc/9005/fd
========= About to call close_range() =======
/proc/self/fd/0 ==> /dev/pts/1
/proc/self/fd/1 ==> /dev/pts/1
/proc/self/fd/2 ==> /dev/pts/1
/proc/self/fd/3 ==> /proc/9005/fd
Note that the lines showing the pathname /proc/9005/fd result from the
calls to opendir(3).
Program source
#define _GNU_SOURCE
#include <dirent.h>
#include <fcntl.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/syscall.h>
#include <unistd.h>
/* Show the contents of the symbolic links in /proc/self/fd */
static void
show_fds(void)
{
DIR *dirp;
char path[PATH_MAX], target[PATH_MAX];
ssize_t len;
struct dirent *dp;
dirp = opendir("/proc/self/fd");
if (dirp == NULL) {
perror("opendir");
exit(EXIT_FAILURE);
}
for (;;) {
dp = readdir(dirp);
if (dp == NULL)
break;
if (dp->d_type == DT_LNK) {
snprintf(path, sizeof(path), "/proc/self/fd/%s",
dp->d_name);
len = readlink(path, target, sizeof(target));
printf("%s ==> %.*s\n", path, (int) len, target);
}
}
closedir(dirp);
}
int
main(int argc, char *argv[])
{
int fd;
for (size_t j = 1; j < argc; j++) {
fd = open(argv[j], O_RDONLY);
if (fd == -1) {
perror(argv[j]);
exit(EXIT_FAILURE);
}
printf("%s opened as FD %d\n", argv[j], fd);
}
show_fds();
printf("========= About to call close_range() =======\n");
if (syscall(SYS_close_range, 3, ~0U, 0) == -1) {
perror("close_range");
exit(EXIT_FAILURE);
}
show_fds();
exit(EXIT_FAILURE);
}
SEE ALSO
close(2)
Linux man-pages 6.03 2023-02-10 close_range(2)
Generated by dwww version 1.15 on Thu Jun 20 14:27:15 CEST 2024.