The branch main has been updated by markj:
URL:
https://cgit.FreeBSD.org/src/commit/?id=efadb5c2a908a08e98f917ef6e6e65c73e8d04af
commit efadb5c2a908a08e98f917ef6e6e65c73e8d04af
Author: Ricardo Branco <rbra...@suse.de>
AuthorDate: 2025-05-17 17:10:19 +0000
Commit: Mark Johnston <ma...@freebsd.org>
CommitDate: 2025-07-06 23:08:41 +0000
Add manpages for O_CLOFORK flag and others
Reviewed by: kib
MFC after: 1 month
Pull Request: https://github.com/freebsd/freebsd-src/pull/1698
---
lib/libc/gen/dup3.3 | 15 +++++++++++++--
lib/libsys/accept.2 | 14 +++++++++++++-
lib/libsys/closefrom.2 | 9 ++++++++-
lib/libsys/execve.2 | 7 +++++--
lib/libsys/fcntl.2 | 43 +++++++++++++++++++++++++++++++++++++++----
lib/libsys/fork.2 | 12 +++++++++++-
lib/libsys/open.2 | 29 ++++++++++++++++++++++++++++-
lib/libsys/pipe.2 | 9 ++++++++-
lib/libsys/recv.2 | 3 ++-
lib/libsys/socket.2 | 13 +++++++++++--
lib/libsys/socketpair.2 | 5 +++--
11 files changed, 141 insertions(+), 18 deletions(-)
diff --git a/lib/libc/gen/dup3.3 b/lib/libc/gen/dup3.3
index f2798930797b..338a9ae74c64 100644
--- a/lib/libc/gen/dup3.3
+++ b/lib/libc/gen/dup3.3
@@ -22,7 +22,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 16, 2013
+.Dd May 17, 2025
.Dt DUP3 3
.Os
.Sh NAME
@@ -47,6 +47,11 @@ The close-on-exec flag on the new file descriptor is
determined by the
bit in
.Fa flags .
.Pp
+The close-on-fork flag on the new file descriptor is determined by the
+.Dv O_CLOFORK
+bit in
+.Fa flags .
+.Pp
If
.Fa oldd
\*(Ne
@@ -91,7 +96,9 @@ argument.
The
.Fa flags
argument has bits set other than
-.Dv O_CLOEXEC .
+.Dv O_CLOEXEC
+or
+.Dv O_CLOFORK .
.El
.Sh SEE ALSO
.Xr accept 2 ,
@@ -112,3 +119,7 @@ The
.Fn dup3
function appeared in
.Fx 10.0 .
+The
+.Dv O_CLOFORK
+flag appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/accept.2 b/lib/libsys/accept.2
index 53926b3153d2..2da2af066a5b 100644
--- a/lib/libsys/accept.2
+++ b/lib/libsys/accept.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd October 9, 2014
+.Dd May 17, 2025
.Dt ACCEPT 2
.Os
.Sh NAME
@@ -85,6 +85,13 @@ and the close-on-exec flag on the new file descriptor can be
set via the
flag in the
.Fa flags
argument.
+Similarly, the
+.Dv O_CLOFORK
+property can be set via the
+.Dv SOCK_CLOFORK
+flag in the
+.Fa flags
+argument.
.Pp
If no pending connections are
present on the queue, and the original socket
@@ -234,3 +241,8 @@ The
.Fn accept4
system call appeared in
.Fx 10.0 .
+.Pp
+The
+.Dv SOCK_CLOFORK
+flag appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/closefrom.2 b/lib/libsys/closefrom.2
index aaa4c55607ac..1885a6fdeaa8 100644
--- a/lib/libsys/closefrom.2
+++ b/lib/libsys/closefrom.2
@@ -23,7 +23,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd March 3, 2022
+.Dd May 17, 2025
.Dt CLOSEFROM 2
.Os
.Sh NAME
@@ -59,6 +59,8 @@ Supported
.Bl -tag -width ".Dv CLOSE_RANGE_CLOEXEC"
.It Dv CLOSE_RANGE_CLOEXEC
Set the close-on-exec flag on descriptors in the range instead of closing them.
+.It Dv CLOSE_RANGE_CLOFORK
+Set the close-on-fork flag on descriptors in the range instead of closing them.
.El
.Sh RETURN VALUES
Upon successful completion,
@@ -90,3 +92,8 @@ The
.Fn closefrom
function first appeared in
.Fx 8.0 .
+.Pp
+The
+.Dv CLOSE_RANGE_CLOFORK
+flag appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/execve.2 b/lib/libsys/execve.2
index 5a35980e9555..dc85b9321e48 100644
--- a/lib/libsys/execve.2
+++ b/lib/libsys/execve.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd January 26, 2022
+.Dd July 02, 2025
.Dt EXECVE 2
.Os
.Sh NAME
@@ -127,7 +127,10 @@ flag is set (see
and
.Xr fcntl 2 ) .
Descriptors that remain open are unaffected by
-.Fn execve .
+.Fn execve ,
+except those with the close-on-fork flag
+.Dv FD_CLOFORK
+which is cleared from all file descriptors.
If any of the standard descriptors (0, 1, and/or 2) are closed at the
time
.Fn execve
diff --git a/lib/libsys/fcntl.2 b/lib/libsys/fcntl.2
index 604de43e5e8c..3cf8adc29f88 100644
--- a/lib/libsys/fcntl.2
+++ b/lib/libsys/fcntl.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd June 5, 2025
+.Dd June 24, 2025
.Dt FCNTL 2
.Os
.Sh NAME
@@ -81,6 +81,13 @@ to remain open across
.Xr execve 2
system calls.
.It
+The fork-on-exec flag
+.Dv FD_CLOFORK
+associated with the new file descriptor is cleared, so the file descriptor is
+to remain open across
+.Xr fork 2
+system calls.
+.It
The
.Dv FD_RESOLVE_BENEATH
flag, described below, will be set if it was set on the original
@@ -95,6 +102,15 @@ flag associated with the new file descriptor is set, so the
file descriptor
is closed when
.Xr execve 2
system call executes.
+.It Dv F_DUPFD_CLOFORK
+Like
+.Dv F_DUPFD ,
+but the
+.Dv FD_CLOFORK
+flag associated with the new file descriptor is set, so the file descriptor
+is closed when
+.Xr fork 2
+system call executes.
.It Dv F_DUP2FD
It is functionally equivalent to
.Bd -literal -offset indent
@@ -117,6 +133,11 @@ Use
.Fn dup2
instead of
.Dv F_DUP2FD .
+.It Dv F_DUP3FD
+Used to implement the
+.Fn dup3
+call.
+Do not use it.
.It Dv F_GETFD
Get the flags associated with the file descriptor
.Fa fd .
@@ -128,6 +149,10 @@ The file will be closed upon execution of
.Fa ( arg
is ignored).
Otherwise, the file descriptor will remain open.
+.It Dv FD_CLOFORK
+The file will be closed upon execution of the
+.Fn fork
+family of system calls.
.It Dv FD_RESOLVE_BENEATH
All path name lookups relative to that file descriptor
will behave as if the lookup had
@@ -153,7 +178,8 @@ descriptor to also have the flag set.
Set flags associated with
.Fa fd .
The available flags are
-.Dv FD_CLOEXEC
+.Dv FD_CLOEXEC ,
+.Dv FD_CLOFORK
and
.Dv FD_RESOLVE_BENEATH .
The
@@ -785,8 +811,10 @@ for the reasons as stated in
.Sh STANDARDS
The
.Dv F_DUP2FD
-constant is non portable.
-It is provided for compatibility with AIX and Solaris.
+and
+.Dv F_DUP3FD
+constants are not portable.
+They are provided for compatibility with AIX and Solaris.
.Pp
Per
.St -susv4 ,
@@ -811,3 +839,10 @@ The
.Dv F_DUP2FD
constant first appeared in
.Fx 7.1 .
+.Pp
+The
+.Dv F_DUPFD_CLOFORK
+and
+.Dv F_DUP3FD
+flags appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/fork.2 b/lib/libsys/fork.2
index 7d548a42890d..e59b208a9ff5 100644
--- a/lib/libsys/fork.2
+++ b/lib/libsys/fork.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 5, 2021
+.Dd May 17, 2024
.Dt FORK 2
.Os
.Sh NAME
@@ -68,6 +68,16 @@ by the parent.
This descriptor copying is also used by the shell to
establish standard input and output for newly created processes
as well as to set up pipes.
+Any file descriptors that were marked with the close-on-fork flag,
+.Dv FD_CLOFORK
+.Po see
+.Fn fcntl 2
+and
+.Dv O_CLOFORK
+in
+.Fn open 2
+.Pc ,
+will not be present in the child process, but remain open in the parent.
.It
The child process' resource utilizations
are set to 0; see
diff --git a/lib/libsys/open.2 b/lib/libsys/open.2
index 84c4f02fce8a..a0e905a8f375 100644
--- a/lib/libsys/open.2
+++ b/lib/libsys/open.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd April 3, 2025
+.Dd May 17, 2025
.Dt OPEN 2
.Os
.Sh NAME
@@ -195,6 +195,9 @@ error if file is not a directory
.It Dv O_CLOEXEC
automatically close file on
.Xr execve 2
+.It Dv O_CLOFORK
+automatically close file on any child process created with
+.Fn fork 2
.It Dv O_VERIFY
verify the contents of the file with
.Xr mac_veriexec 4
@@ -360,6 +363,27 @@ may be used to set
.Dv FD_CLOEXEC
flag for the newly returned file descriptor.
.Pp
+.Dv O_CLOFORK
+may be used to set
+.Dv FD_CLOFORK
+flag for the newly returned file descriptor.
+The file will be closed on any child process created with
+.Fn fork 2 ,
+.Fn vfork 2
+or
+.Fn rfork 2
+with the
+.Dv RFFDG
+flag, remaining open in the parent.
+Both the
+.Dv O_CLOEXEC
+and
+.Dv O_CLOFORK
+flags can be modified with the
+.Dv F_SETFD
+.Fn fcntl 2
+command.
+.Pp
.Dv O_VERIFY
may be used to indicate to the kernel that the contents of the file should
be verified before allowing the open to proceed.
@@ -846,6 +870,9 @@ function was introduced in
appeared in 13.0.
.Dv O_NAMEDATTR
appeared in 15.0.
+.Dv O_CLOFORK
+appeared in
+.Fx 15.0 .
.Sh BUGS
The
.Fa mode
diff --git a/lib/libsys/pipe.2 b/lib/libsys/pipe.2
index 9531c9717395..37d6eba420de 100644
--- a/lib/libsys/pipe.2
+++ b/lib/libsys/pipe.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd December 1, 2017
+.Dd May 17, 2025
.Dt PIPE 2
.Os
.Sh NAME
@@ -64,6 +64,8 @@ list, defined in
.Bl -tag -width ".Dv O_NONBLOCK"
.It Dv O_CLOEXEC
Set the close-on-exec flag for the new file descriptors.
+.It Dv O_CLOFORK
+Set the close-on-fork flag for the new file descriptors.
.It Dv O_NONBLOCK
Set the non-blocking flag for the ends of the pipe.
.El
@@ -173,3 +175,8 @@ function became a wrapper around
.Fn pipe2
in
.Fx 11.0 .
+.Pp
+The
+.Dv O_CLOFORK
+flag appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/recv.2 b/lib/libsys/recv.2
index f3ee60b75663..b78cd70b8a1d 100644
--- a/lib/libsys/recv.2
+++ b/lib/libsys/recv.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd July 30, 2022
+.Dd May 17, 2025
.Dt RECV 2
.Os
.Sh NAME
@@ -164,6 +164,7 @@ one or more of the values:
.It Dv MSG_WAITALL Ta wait for full request or error
.It Dv MSG_DONTWAIT Ta do not block
.It Dv MSG_CMSG_CLOEXEC Ta set received fds close-on-exec
+.It Dv MSG_CMSG_CLOFORK Ta set received fds close-on-fork
.It Dv MSG_WAITFORONE Ta do not block after receiving the first message
(only for
.Fn recvmmsg
diff --git a/lib/libsys/socket.2 b/lib/libsys/socket.2
index a383cbcc4d80..b211611c6354 100644
--- a/lib/libsys/socket.2
+++ b/lib/libsys/socket.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd January 15, 2023
+.Dd May 17, 2025
.Dt SOCKET 2
.Os
.Sh NAME
@@ -121,6 +121,7 @@ argument:
.Pp
.Bd -literal -offset indent -compact
SOCK_CLOEXEC Set close-on-exec on the new descriptor,
+SOCK_CLOFORK Set close-on-fork on the new descriptor,
SOCK_NONBLOCK Set non-blocking mode on the new socket
.Ed
.Pp
@@ -331,7 +332,10 @@ argument of
.Fn socket .
The
.Dv SOCK_CLOEXEC
-flag is expected to conform to the next revision of the
+and
+.Dv SOCK_CLOFORK
+flags are expected to conform to
+.St -p1003.1-2024 .
.Tn POSIX
standard.
The
@@ -347,3 +351,8 @@ The
.Fn socket
system call appeared in
.Bx 4.2 .
+.Pp
+The
+.Dv SOCK_CLOFORK
+flag appeared in
+.Fx 15.0 .
diff --git a/lib/libsys/socketpair.2 b/lib/libsys/socketpair.2
index 5874a0791f4d..60dec74f9cc2 100644
--- a/lib/libsys/socketpair.2
+++ b/lib/libsys/socketpair.2
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd February 10, 2018
+.Dd May 17, 2025
.Dt SOCKETPAIR 2
.Os
.Sh NAME
@@ -56,7 +56,8 @@ and
The two sockets are indistinguishable.
.Pp
The
-.Dv SOCK_CLOEXEC
+.Dv SOCK_CLOEXEC ,
+.Dv SOCK_CLOFORK
and
.Dv SOCK_NONBLOCK
flags in the
