Skip to contentSkip to conversation

close_range.2: new page documenting close_range(2)

PATCH Superseded Stephen Kitt 4 participants 5 messages Dec 9, 2020 – Dec 12, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v2 of 6 Superseded Latest is v6 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 close_range.2: new page documenting close_range(2)

This documents close_range(2) based on information in 278a5fbaed89dacd04e9d052f4594ffd0e0585de and 60997c3d45d9a67daf01c56d805ae4fec37e0bd8.

---
V2: unsigned int to match the kernel declarations
groff and grammar tweaks CLOSE_RANGE_UNSHARE unshares *and* closes Explain that EMFILE and ENOMEM can occur with C_R_U "Conforming to" phrasing
Detailed explanation of CLOSE_RANGE_UNSHARE Reading /proc isn't common

 man2/close_range.2 | 138 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 man2/close_range.2
man2/close_range.2 new file +138 -0
new file mode 100644
index 000000000..403142b33
@@ -0,0 +1,138 @@
+.\" Copyright (c) 2020 Stephen Kitt <[email protected]>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.TH CLOSE_RANGE 2 2020-12-08 "Linux" "Linux Programmer's Manual"
+.SH NAME
+close_range \- close all file descriptors in a given range
+.SH SYNOPSIS
+.nf
+.B #include <linux/close_range.h>
+.PP
+.BI "int close_range(unsigned int " first ", unsigned int " last ", unsigned int " flags );
+.fi
+.SH DESCRIPTION
+The
+.BR close_range ()
+system call closes all open file descriptors from
+.I first
+to
+.I last
+(included).
+.PP
+Errors closing a given file descriptor are currently ignored.
+.PP
+.I flags
+can be set to
+.B CLOSE_RANGE_UNSHARE
+to unshare the range of file descriptors from any other processes,
+before closing them, avoiding races with other threads sharing the
+file descriptor table.
+.SH RETURN VALUE
+On success,
+.BR close_range ()
+returns 0.
+On error, \-1 is returned and
+.I errno
+is set to indicate the cause of the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I flags
+is not valid, or
+.I first
+is greater than
+.IR last .
+.PP
+The following can occur with
+.B CLOSE_RANGE_UNSHARE
+(when constructing the new descriptor table):
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached
+(see the description of
+.B RLIMIT_NOFILE
+in
+.BR getrlimit (2)).
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.SH VERSIONS
+.BR close_range ()
+first appeared in Linux 5.9.
+.SH CONFORMING TO
+.BR close_range ()
+is a nonstandard function that is also present on FreeBSD.
+.SH NOTES
+Currently, there is no glibc wrapper for this system call; call it using
+.BR syscall (2).
+.PP
+.B CLOSE_RANGE_UNSHARE
+is conceptually equivalent to
+.PP
+.in +4n
+.EX
+unshare(CLONE_FILES);
+close_range(first, last, 0);
+.EE
+.in
+.PP
+but can be more efficient: if the unshared range extends past the
+current maximum number of file descriptors allocated in the caller's
+file descriptor table (the common case when
+.I last
+is
+.BR ~0U ),
+the kernel will unshare a new file descriptor
+table for the caller up to
+.IR first .
+This avoids subsequent close calls entirely; the whole operation is
+complete once the table is unshared.
+.SH USE CASES
+.\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de
+.\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8
+.SS Closing file descriptors before exec
+File descriptors can be closed safely using
+.PP
+.in +4n
+.EX
+/* we don't want anything past stderr here */
+close_range(3, ~0U, CLOSE_RANGE_UNSHARE);
+execve(....);
+.EE
+.in
+.SS 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
+.I /proc/self/fd/
+and calling
+.BR close (2)
+on each one.
+.BR close_range ()
+can take care of this without requiring
+.I /proc
+and with a single system call, which provides significant performance
+benefits.
+.SH SEE ALSO
+.BR close (2)

base-commit: b5dae3959625f5ff378e9edf9139057d1c06bb55

Signature · 1 line
2.20.1
#1 lore raw

Hi Stephen,

A few more comments below.

Michael, please have a look at them too.

Christian, do you have any program that you used to test the syscall that could be added as an example program to the page?

Thanks,

Alex

Quoted 46 lines · Stephen Kitt

This documents close_range(2) based on information in 278a5fbaed89dacd04e9d052f4594ffd0e0585de and 60997c3d45d9a67daf01c56d805ae4fec37e0bd8.

---
V2: unsigned int to match the kernel declarations
groff and grammar tweaks CLOSE_RANGE_UNSHARE unshares *and* closes Explain that EMFILE and ENOMEM can occur with C_R_U "Conforming to" phrasing
Detailed explanation of CLOSE_RANGE_UNSHARE Reading /proc isn't common

 man2/close_range.2 | 138 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 man2/close_range.2
man2/close_range.2 new file +22 -0
new file mode 100644
index 000000000..403142b33
@@ -0,0 +1,138 @@
+.\" Copyright (c) 2020 Stephen Kitt <[email protected]>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.

man2/close_range.2 line 32

Quoted 10 lines
man2/close_range.2 new file +10 -0
+.\" %%%LICENSE_END
+.\"
+.TH CLOSE_RANGE 2 2020-12-08 "Linux" "Linux Programmer's Manual"
+.SH NAME
+close_range \- close all file descriptors in a given range
+.SH SYNOPSIS
+.nf
+.B #include <linux/close_range.h>
+.PP
+.BI "int close_range(unsigned int " first ", unsigned int " last ", unsigned int " flags );

This line overflows an 80-col terminal. Fix:

.BI "int close_range(unsigned int " first ", unsigned int " last ,
.BI " unsigned int " flags );

man2/close_range.2 line 33

Quoted 1 line
man2/close_range.2 new file +1 -0
+.fi

Please, add a note here that there is no wrapper for this syscall, as in other syscalls without wrapper (see membarrier(2) as an example). That way it's easier to grep, if all pages have the same notice.

Quoted 7 lines
man2/close_range.2 new file +7 -0
+.SH DESCRIPTION
+The
+.BR close_range ()
+system call closes all open file descriptors from
+.I first
+to
+.I last

man2/close_range.2 line 50

Quoted 10 lines
man2/close_range.2 new file +10 -0
+(included).
+.PP
+Errors closing a given file descriptor are currently ignored.
+.PP
+.I flags
+can be set to
+.B CLOSE_RANGE_UNSHARE
+to unshare the range of file descriptors from any other processes,
+before closing them, avoiding races with other threads sharing the
+file descriptor table.

Please use semantic newlines.
See man-pages(7)::STYLE GUIDE::Use semantic newlines

Quoted 28 lines
man2/close_range.2 new file +28 -0
+.SH RETURN VALUE
+On success,
+.BR close_range ()
+returns 0.
+On error, \-1 is returned and
+.I errno
+is set to indicate the cause of the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I flags
+is not valid, or
+.I first
+is greater than
+.IR last .
+.PP
+The following can occur with
+.B CLOSE_RANGE_UNSHARE
+(when constructing the new descriptor table):
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached
+(see the description of
+.B RLIMIT_NOFILE
+in
+.BR getrlimit (2)).
+.TP
+.B ENOMEM

man2/close_range.2 line 88

Quoted 10 lines
man2/close_range.2 new file +10 -0
+Insufficient kernel memory was available.
+.SH VERSIONS
+.BR close_range ()
+first appeared in Linux 5.9.
+.SH CONFORMING TO
+.BR close_range ()
+is a nonstandard function that is also present on FreeBSD.
+.SH NOTES
+Currently, there is no glibc wrapper for this system call; call it using
+.BR syscall (2).

I can see that this notice is also present on a few pages, but the one in membarrier(2) is more extended.

Please, copy the notices from membarrier(2).
There's one in SYNOPSIS, and one in NOTES.

Quoted 12 lines
man2/close_range.2 new file +12 -0
+.PP
+.B CLOSE_RANGE_UNSHARE
+is conceptually equivalent to
+.PP
+.in +4n
+.EX
+unshare(CLONE_FILES);
+close_range(first, last, 0);
+.EE
+.in
+.PP
+but can be more efficient: if the unshared range extends past the

man2/close_range.2 line 110

Quoted 10 lines
man2/close_range.2 new file +10 -0
+current maximum number of file descriptors allocated in the caller's
+file descriptor table (the common case when
+.I last
+is
+.BR ~0U ),
+the kernel will unshare a new file descriptor
+table for the caller up to
+.IR first .
+This avoids subsequent close calls entirely; the whole operation is
+complete once the table is unshared.

I think the above is more suitable for the DESCRIPTION, but what are your thoughts, mtk?

man2/close_range.2 line 111

Quoted 1 line
man2/close_range.2 new file +1 -0
+.SH USE CASES

This section is unconventional. Please move that text to one of the traditional sections. I think DESCRIPTION would be the best place for this.

For a list of the traditional sections,
see man-pages(7)::DESCRIPTION::Sections within a manual page

Quoted 30 lines
man2/close_range.2 new file +27 -0
+.\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de
+.\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8
+.SS Closing file descriptors before exec
+File descriptors can be closed safely using
+.PP
+.in +4n
+.EX
+/* we don't want anything past stderr here */
+close_range(3, ~0U, CLOSE_RANGE_UNSHARE);
+execve(....);
+.EE
+.in
+.SS 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
+.I /proc/self/fd/
+and calling
+.BR close (2)
+on each one.
+.BR close_range ()
+can take care of this without requiring
+.I /proc
+and with a single system call, which provides significant performance
+benefits.
+.SH SEE ALSO
+.BR close (2)

base-commit: b5dae3959625f5ff378e9edf9139057d1c06bb55

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es
#2 lore raw

Hi Alejandro,

Quoted 1 line · Alejandro Colomar (man-pages)

A few more comments below.

Thanks for all the detailed reviews! (Same goes to everyone reviewing this yesterday, thanks for helping turn my not-so-great attempt into something really useful.)

Quoted 4 lines

Michael, please have a look at them too.

Christian, do you have any program that you used to test the syscall that could be added as an example program to the page?

I have some example code that I could turn into an example program, but I imagine Christian has better code than me ;-).

Quoted 7 lines
Quoted 2 lines

+.BI "int close_range(unsigned int " first ", unsigned int " last ", unsigned int " flags );

This line overflows an 80-col terminal. Fix:

.BI "int close_range(unsigned int " first ", unsigned int " last ,
.BI " unsigned int " flags );

Noted, thanks.

Quoted 5 lines
Quoted 1 line

+.fi

Please, add a note here that there is no wrapper for this syscall, as in other syscalls without wrapper (see membarrier(2) as an example). That way it's easier to grep, if all pages have the same notice.

Ah, right, I used pidfd_open(2) as an example, where it's mentioned later.

Quoted 2 lines

Please use semantic newlines.
See man-pages(7)::STYLE GUIDE::Use semantic newlines

Noted, thanks.

Quoted 9 lines
Quoted 3 lines

+.SH NOTES
+Currently, there is no glibc wrapper for this system call; call it using +.BR syscall (2).

I can see that this notice is also present on a few pages, but the one in membarrier(2) is more extended.

Please, copy the notices from membarrier(2).
There's one in SYNOPSIS, and one in NOTES.

Will do!

Quoted 7 lines
Quoted 1 line

+.SH USE CASES

This section is unconventional. Please move that text to one of the traditional sections. I think DESCRIPTION would be the best place for this.

For a list of the traditional sections,
see man-pages(7)::DESCRIPTION::Sections within a manual page

Indeed; it grew out of pidfd_open's "Use cases" section but making all this part of the description would be much better.

I'll wait and see if there are other comments, and send a v3 addressing all the above.

Regards,

Stephen

#3 lore raw
In reply to Alejandro Colomar (man-pages)
Quoted 37 lines · Alejandro Colomar (man-pages)

Hi Stephen,

A few more comments below.

Michael, please have a look at them too.

Christian, do you have any program that you used to test the syscall that could be added as an example program to the page?

Thanks,

Alex

Quoted 23 lines · Stephen Kitt

This documents close_range(2) based on information in 278a5fbaed89dacd04e9d052f4594ffd0e0585de and 60997c3d45d9a67daf01c56d805ae4fec37e0bd8.

---
V2: unsigned int to match the kernel declarations
groff and grammar tweaks CLOSE_RANGE_UNSHARE unshares *and* closes Explain that EMFILE and ENOMEM can occur with C_R_U "Conforming to" phrasing
Detailed explanation of CLOSE_RANGE_UNSHARE Reading /proc isn't common

 man2/close_range.2 | 138 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 man2/close_range.2
man2/close_range.2 new file +0 -0
new file mode 100644
index 000000000..403142b33

[...]

Quoted 4 lines
Quoted 1 line

+.SH USE CASES

This section is unconventional. Please move that text to one of the traditional sections. I think DESCRIPTION would be the best place for this.

Actually, I'd just drop this SH line, and keep the subsections where they are in NOTES.

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#4 lore raw
In reply to Alejandro Colomar (man-pages)
Quoted 8 lines · Alejandro Colomar (man-pages)

Hi Stephen,

A few more comments below.

Michael, please have a look at them too.

Christian, do you have any program that you used to test the syscall that could be added as an example program to the page?

As with all non-trivial feature patchsets going through my tree we've added selftests. :)

tools/testing/selftests/core/close_range_test.c

It should be fairly simply to extract a tinified example from there.

Thanks!
Christian