git: a4981ededef3 - main - kqueue.2: document KQUEUE_CPONFORK

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=a4981ededef3c2d867ddd991905e4b65bc917a62

commit a4981ededef3c2d867ddd991905e4b65bc917a62
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2025-10-08 03:06:20 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2025-10-18 05:12:37 +0000

    kqueue.2: document KQUEUE_CPONFORK
    
    Reviewed by:    markj
    Sponsored by:   The FreeBSD Foundation
    MFC after:      2 weeks
    Differential revision:  https://reviews.freebsd.org/D52045
---
 lib/libsys/kqueue.2 | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/lib/libsys/kqueue.2 b/lib/libsys/kqueue.2
index 96c9b0222a37..a8ebabf02cf7 100644
--- a/lib/libsys/kqueue.2
+++ b/lib/libsys/kqueue.2
@@ -97,10 +97,37 @@ system call also creates a new kernel event queue, and additionally takes
 a
 .Fa flags
 argument, which is a bitwise-inclusive OR of the following flags:
-.Bl -tag -width "KQUEUE_CLOEXEC"
+.Bl -tag -width "KQUEUE_CPONFORK"
 .It Dv KQUEUE_CLOEXEC
 The returned file descriptor is automatically closed on
 .Xr execve 2
+.It Dv KQUEUE_CPONFORK
+When this flag is set, the created kqueue is copied into
+the child process on
+.Xr fork 2
+calls.
+The kqueue descriptor index of the new kqueue will be inherited by the child,
+that is, the numeric value of the descriptor will remain the same.
+.Pp
+Copying is deep, that is, each registered event in the original kqueue is
+copied (and not shared) into the new kqueue.
+This is contrary to how other descriptor types are handled upon
+.Xr fork 2 ,
+where the copied file descriptor references the same file object
+as the source descriptor (shallow copy).
+.Pp
+By default, in other words, when the flag is not set, kqueues from
+the parent are not copied on fork to the child process.
+The corresponding file descriptor indeces are unused in the child.
+.Pp
+Registered events that reference file descriptors which are not
+duplicated on fork, are not copied into the new kqueue.
+For instance, if the event references a file descriptor opened with the
+.Dv O_CLOEXEC
+flag set, it is not copied.
+Similarly, if event references a kqueue opened without the
+.Dv KQUEUE_CPONFORK
+flag, the event is not copied.
 .El
 .Pp
 The