[PATCH 1/3] man3/creal.3, man3/cimag.3: Standardize style and history

[PATCH 1/3] man3/creal.3, man3/cimag.3: Standardize style and history

[Simon Essien]

Consolidated VERSIONS and HISTORY sections to match project standards.
Moved GNU extension notes for __real__ and __imag__ to a clearer
format within VERSIONS.

Signed-off-by: Simon Essien <champbreed1@gmail.com>
---
 man/man3/cimag.3 | 11 ++++-------
 man/man3/creal.3 | 11 ++++-------
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/man/man3/cimag.3 b/man/man3/cimag.3
index 39eeb1007..946e095a8 100644
--- a/man/man3/cimag.3
+++ b/man/man3/cimag.3
@@ -45,14 +45,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC also supports __imag__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR creal (3),
-.BR complex (7)
diff --git a/man/man3/creal.3 b/man/man3/creal.3
index be07d8273..d05125274 100644
--- a/man/man3/creal.3
+++ b/man/man3/creal.3
@@ -43,14 +43,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC supports also __real__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR cimag (3),
-.BR complex (7)
-- 
2.51.0

[PATCH 1/2] seccomp_unotify.2: confirm listener limits and signal behavior

[Simon Essien]

- Remove FIXME regarding the single-listener limit. Verification
  via test program confirms the kernel returns EBUSY as documented.
- Remove FIXME regarding SA_RESTART oddity. The behavior is
  established and documented; the internal query is no longer required.
---
 man/man2/seccomp_unotify.2 | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/man/man2/seccomp_unotify.2 b/man/man2/seccomp_unotify.2
index b3aedad4b..f1ff13513 100644
--- a/man/man2/seccomp_unotify.2
+++ b/man/man2/seccomp_unotify.2
@@ -89,8 +89,6 @@ Consequently, the return value of the (successful)
 call is a new "listening"
 file descriptor that can be used to receive notifications.
 Only one "listening" seccomp filter can be installed for a thread.
-.\" FIXME
-.\" Is the last sentence above correct?
 .\"
 .\" Kees Cook (25 Oct 2020) notes:
 .\"
@@ -1148,16 +1146,6 @@ that would
 normally be restarted by the
 .B SA_RESTART
 flag.
-.\" FIXME
-.\" About the above, Kees Cook commented:
-.\"
-.\" Does this need fixing? I imagine the correct behavior for this case
-.\" would be a response to _SEND of EINPROGRESS and the target would see
-.\" EINTR normally?
-.\"
-.\" I mean, it's not like seccomp doesn't already expose weirdness with
-.\" syscall restarts.  Not even arm64 compat agrees[3] with arm32 in this
-.\" regard.  :(
 .
 .\" FIXME
 .\" Michael Kerrisk:
-- 
2.51.0

[PATCH 2/3] man2: update glibc wrapper status and clean up FIXMEs

[Simon Essien]

Update seccomp(2) to reflect that glibc 2.33 added a wrapper.
Update sched_setattr(2) to remove obsolete FIXME markers, as the
lack of a glibc wrapper is already correctly noted in the text.

Signed-off-by: Simon Essien <champbreed1@gmail.com>
---
 man/man2/sched_setattr.2 | 5 +----
 man/man2/seccomp.2       | 4 ++--
 2 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/man/man2/sched_setattr.2 b/man/man2/sched_setattr.2
index 6d5718022..c8010b8fa 100644
--- a/man/man2/sched_setattr.2
+++ b/man/man2/sched_setattr.2
@@ -460,7 +460,6 @@ does not include all CPUs in the system
 Linux.
 .SH HISTORY
 Linux 3.14.
-.\" FIXME . Add glibc version
 .SH NOTES
 glibc does not provide wrappers for these system calls;
 call them using
@@ -482,9 +481,7 @@ provides a superset of the functionality of
 and (partially)
 .BR getpriority (2).
 .SH BUGS
-In Linux versions up to
-.\" FIXME . patch sent to Peter Zijlstra
-3.15,
+In Linux versions up to 3.15,
 .BR sched_setattr ()
 failed with the error
 .B EFAULT
diff --git a/man/man2/seccomp.2 b/man/man2/seccomp.2
index 125794880..685ed4713 100644
--- a/man/man2/seccomp.2
+++ b/man/man2/seccomp.2
@@ -25,7 +25,7 @@ Standard C library
 .fi
 .P
 .IR Note :
-glibc provides no wrapper for
+Before glibc 2.33, glibc provided no wrapper for
 .BR seccomp (),
 necessitating the use of
 .BR syscall (2).
@@ -863,7 +863,7 @@ be determined.
 Linux.
 .SH HISTORY
 Linux 3.17.
-.\" FIXME . Add glibc version
+Glibc 2.33.
 .SH NOTES
 Rather than hand-coding seccomp filters as shown in the example below,
 you may prefer to employ the
-- 
2.51.0

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

[Simon Essien]

- 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

[PATCH 1/3] man3/creal.3, man3/cimag.3: Standardize style and history

[Simon Essien]

Consolidated VERSIONS and HISTORY sections to match project standards.
Moved GNU extension notes for __real__ and __imag__ to a clearer
format within VERSIONS.

Signed-off-by: Simon Essien <champbreed1@gmail.com>
---
 man/man3/cimag.3 | 11 ++++-------
 man/man3/creal.3 | 11 ++++-------
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/man/man3/cimag.3 b/man/man3/cimag.3
index 39eeb1007..946e095a8 100644
--- a/man/man3/cimag.3
+++ b/man/man3/cimag.3
@@ -45,14 +45,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC also supports __imag__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR creal (3),
-.BR complex (7)
diff --git a/man/man3/creal.3 b/man/man3/creal.3
index be07d8273..d05125274 100644
--- a/man/man3/creal.3
+++ b/man/man3/creal.3
@@ -43,14 +43,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC supports also __real__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR cimag (3),
-.BR complex (7)
-- 
2.51.0

[PATCH 1/3] man3/creal.3, man3/cimag.3: Standardize style and history

[Simon Essien]

Consolidated VERSIONS and HISTORY sections to match project standards.
Moved GNU extension notes for __real__ and __imag__ to a clearer
format within VERSIONS.

Signed-off-by: Simon Essien <champbreed1@gmail.com>
---
 man/man3/cimag.3 | 11 ++++-------
 man/man3/creal.3 | 11 ++++-------
 2 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/man/man3/cimag.3 b/man/man3/cimag.3
index 39eeb1007..946e095a8 100644
--- a/man/man3/cimag.3
+++ b/man/man3/cimag.3
@@ -45,14 +45,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC also supports __imag__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR creal (3),
-.BR complex (7)
diff --git a/man/man3/creal.3 b/man/man3/creal.3
index be07d8273..d05125274 100644
--- a/man/man3/creal.3
+++ b/man/man3/creal.3
@@ -43,14 +43,11 @@ T{
 T}	Thread safety	MT-Safe
 .TE
 .SH VERSIONS
-GCC supports also __real__.
-That is a GNU extension.
+Available since glibc 2.1.
+GCC also supports the
+.BR __real__
+keyword (a GNU extension).
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
-glibc 2.1.
 C99, POSIX.1-2001.
-.SH SEE ALSO
-.BR cabs (3),
-.BR cimag (3),
-.BR complex (7)
-- 
2.51.0