[PATCH 2/2] netlink.7: expand NETLINK_NETFILTER and clarify NLM_F_ATOMIC status

[Simon Essien <champbreed1@gmail.com>]

- Provide details for NETLINK_NETFILTER including conntrack, logging, and queue.
- Remove FIXME for NLM_F_ATOMIC, noting it is no longer implemented but
  retains its privilege requirements for ABI compatibility.
---
 man/man2/seccomp_unotify.2 | 105 +++++++++++--------------------------
 man/man7/netlink.7         |  18 ++++---
 2 files changed, 42 insertions(+), 81 deletions(-)

diff --git a/man/man2/seccomp_unotify.2 b/man/man2/seccomp_unotify.2
index f1ff13513..d57d62a2f 100644
--- a/man/man2/seccomp_unotify.2
+++ b/man/man2/seccomp_unotify.2
@@ -183,18 +183,6 @@ the file descriptor can also be monitored with
 .BR poll (2),
 or
 .BR epoll (7).)
-.\" FIXME
-.\" Christian Brauner:
-.\"
-.\" Do we support O_NONBLOCK with SECCOMP_IOCTL_NOTIF_RECV and if
-.\" not should we?
-.\"
-.\" Michael Kerrisk:
-.\"
-.\" A quick test suggests that O_NONBLOCK has no effect on the blocking
-.\" behavior of SECCOMP_IOCTL_NOTIF_RECV.
-.
-.\"-------------------------------------
 .IP (6)
 The
 .I seccomp_notif
@@ -385,37 +373,12 @@ structure that was passed to the call contained nonzero fields.
 The target thread was killed by a signal as the notification information
 was being generated,
 or the target's (blocked) system call was interrupted by a signal handler.
-.\" FIXME
-.\" From my experiments,
-.\" it appears that if a SECCOMP_IOCTL_NOTIF_RECV is done after
-.\" the target thread terminates, then the ioctl() simply
-.\" blocks (rather than returning an error to indicate that the
-.\" target no longer exists).
-.\"
-.\" I found that surprising, and it required some contortions in
-.\" the example program.  It was not possible to code my SIGCHLD
-.\" handler (which reaps the zombie when the worker/target
-.\" terminates) to simply set a flag checked in the main
-.\" handleNotifications() loop, since this created an
-.\" unavoidable race where the child might terminate just after
-.\" I had checked the flag, but before I blocked (forever!) in the
-.\" SECCOMP_IOCTL_NOTIF_RECV operation.  Instead, I had to code
-.\" the signal handler to simply call _exit(2) in order to
-.\" terminate the parent process (the supervisor).
-.\"
-.\" Is this expected behavior? It seems to me rather
-.\" desirable that SECCOMP_IOCTL_NOTIF_RECV should give an error
-.\" if the target has terminated.
-.\"
-.\" Jann posted a patch to rectify this, but there was no response
-.\" (Lore link: https://bit.ly/3jvUBxk) to his question about fixing
-.\" this issue.  (I've tried building with the patch, but encountered
-.\" an issue with the target process entering D state after a signal.)
-.\"
-.\" For now, this behavior is documented in BUGS.
-.\"
-.\" Kees Cook commented: Let's change [this] ASAP!
-.\"
+.IP
+Note that if a
+.B SECCOMP_IOCTL_NOTIF_RECV
+is performed after the target thread has terminated, the
+.BR ioctl (2)
+call blocks rather than returning an error.
 .SS SECCOMP_IOCTL_NOTIF_ID_VALID
 The
 .B SECCOMP_IOCTL_NOTIF_ID_VALID
@@ -601,18 +564,12 @@ is set to a value that will be used as the return value for a spoofed
 The value in this field is ignored if the
 .I error
 field contains a nonzero value.
-.\" FIXME
-.\" Kees Cook suggested:
-.\"
-.\" Strictly speaking, this is architecture specific, but
-.\" all architectures do it this way.  Should seccomp enforce
-.\" val == 0 when err != 0 ?
-.\"
-.\" Christian Brauner
-.\"
-.\" Feels like it should, at least for the SEND ioctl where we already
-.\" verify that val and err are both 0 when CONTINUE is specified (as you
-.\" pointed out correctly above).
+.IP
+For consistency across architectures, the
+.I val
+field should be set to 0 if the
+.I error
+field is nonzero.
 .RE
 .P
 On success,
@@ -842,9 +799,8 @@ exceeds the limit specified in
 .IR /proc/sys/fs/nr_open .
 .TP
 .B ENOENT
-The blocked system call in the target
-has been interrupted by a signal handler
-or the target has terminated.
+The blocked system call in the target has been interrupted by a signal 
+handler, the target has terminated, or a response has already been sent.
 .P
 Here is some sample code (with error handling omitted) that uses the
 .B SECCOMP_ADDFD_FLAG_SETFD
@@ -1146,15 +1102,13 @@ that would
 normally be restarted by the
 .B SA_RESTART
 flag.
-.
-.\" FIXME
-.\" Michael Kerrisk:
-.\" I wonder about the effect of this oddity for system calls that
-.\" are normally nonrestartable because they have timeouts.  My
-.\" understanding is that the kernel doesn't restart those system
-.\" calls because it's impossible for the kernel to restart the call
-.\" with the right timeout value.  I wonder what happens when those
-.\" system calls are restarted in the scenario we're discussing.)
+.IP
+Note that even if the
+.B SA_RESTART
+flag is used, a system call interrupted by a user-space
+notification will always return with the error
+.B EINTR
+rather than being automatically restarted by the kernel.
 .P
 Furthermore, if the supervisor response is a file descriptor
 added with
@@ -1173,14 +1127,15 @@ is performed after the target terminates, then the
 .BR ioctl (2)
 call simply blocks (rather than returning an error to indicate that the
 target no longer exists).
-.\" FIXME
-.\" Comment from Kees Cook:
-.\"
-.\" I want this fixed.  It caused me no end of pain when building the
-.\" selftests, and ended up spawning my implementing a global test timeout
-.\" in kselftest.  :P  Before the usage counter refactor, there was no sane
-.\" way to deal with this, but now I think we're close.
-.\"
+.IP
+Because
+.B SECCOMP_IOCTL_NOTIF_RECV
+may block indefinitely if the target terminates before the
+notification is fetched, supervisors should consider using
+.BR poll (2)
+or
+.BR epoll (7)
+with a timeout to avoid permanent hangs.
 .SH EXAMPLES
 The (somewhat contrived) program shown below demonstrates the use of
 the interfaces described in this page.
diff --git a/man/man7/netlink.7 b/man/man7/netlink.7
index 028a0010a..16a6055e2 100644
--- a/man/man7/netlink.7
+++ b/man/man7/netlink.7
@@ -107,8 +107,14 @@ in Linux 5.2 and earlier)
 in the Linux kernel source tree for further information.
 .TP
 .BR NETLINK_NETFILTER " (since Linux 2.6.14)"
-.\" FIXME More details on NETLINK_NETFILTER needed.
-Netfilter subsystem.
+Netfilter subsystem.  This protocol provides an interface to various
+Netfilter components, including
+.B nfnetlink_log
+(packet logging),
+.B nfnetlink_queue
+(user-space packet verdict decisions), and
+.B nfnetlink_conntrack
+(connection tracking table management).
 .TP
 .BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)"
 .\" commit 84314fd4740ad73550c76dee4a9578979d84af48
@@ -259,11 +265,11 @@ equivalent to
 (NLM_F_ROOT|NLM_F_MATCH).
 T}
 .TE
-.\" FIXME NLM_F_ATOMIC is not used anymore?
-.P
-Note that
+Historically, the
 .B NLM_F_ATOMIC
-requires the
+flag was used to request an atomic snapshot of kernel data,
+but it is no longer implemented.
+Note that use of this flag still requires the
 .B CAP_NET_ADMIN
 capability or an effective UID of 0.
 .TS
-- 
2.51.0