Clean up the libpsx.3 man page.

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>

1 files changed, 22 insertions, 18 deletions

diff --git a/doc/libpsx.3 b/doc/libpsx.3
index a907d8b..a3535a6 100644
--- a/doc/libpsx.3
+++ b/doc/libpsx.3
@@ -1,4 +1,4 @@
-.TH LIBPSX 3 "2020-01-07" "" "Linux Programmer's Manual"
+.TH LIBPSX 3 "2020-10-13" "" "Linux Programmer's Manual"
 .SH NAME
 psx_syscall3, psx_syscall6 \- POSIX semantics for system calls
 .SH SYNOPSIS
@@ -25,43 +25,47 @@ mechanism glibc maintains consistent UID and GID credentials amongst
 all of the threads associated with the current process. However, other
 credential state is not supported by this abstraction. To support
 these extended kernel managed security attributes,
-.BR libpsx (3)
+.B libpsx
 provides a more generic pair of wrapping system call functions:
-.BR psx_syscall3 "(3) and " psx_syscall6 (3).
+.BR psx_syscall3 "() and " psx_syscall6 ().
 Like the
 .B setxid
-mechanism, the coordination of thread state is arranged by a realtime
-signal SIGRTMAX which is usurped for this process.
+mechanism, the coordination of thread state is mediated by a realtime
+signal. Whereas the
+.B nptl:setxid
+mechanism uses signo=33 (which is hidden by glibc below a redefined
+SIGRTMIN),
+.B libpsx
+usurps SIGRTMAX for this process.
 .PP
 A linker trick of
 .I wrapping
 the
 .BR pthread_create ()
-call with a psx thread registration function is used to allow
+call with a psx thread registration function is used to ensure
 .B libpsx
-to keep track of all pthreads. If that trick is not usable by your application, then the much more cumbersome and fragile
-.B <sys/psx_syscall.h>
-header file.
+can keep track of all pthreads.
 .PP
-An inefficient macrology trick supports the psx_syscall() pseudo
-function which takes 1 to 7 arguments, depending on the needs of the
-caller. The macrology pads out the call to actually use
-.BR psx_syscall3 (3)
+An inefficient macrology trick supports the
+.BR psx_syscall ()
+pseudo function which takes 1 to 7 arguments, depending on the needs
+of the caller. The macrology pads out the call to actually use
+.BR psx_syscall3 ()
 or
-.BR psx_syscall6 (3)
+.BR psx_syscall6 ()
 with zeros filling the missing arguments. While using this in source
 code will make it appear clean, the actual code footprint is
 larger. You are encouraged to use the more explicit
-.BR psx_syscall3 (3)
+.BR psx_syscall3 ()
 and
-.BR psx_syscall6 (3)
-functions.
+.BR psx_syscall6 ()
+functions as needed.
 .SH RETURN VALUE
 The return value for system call functions is generally the value
 returned by the kernel, or \-1 in the case of an error. In such cases
 .BR errno (3)
 is set to the detailed error value. The
-.BR psx_syscall3 " and " psx_syscall6
+.BR psx_syscall3 "() and " psx_syscall6 ()
 functions attempt a single threaded system call and return immediately
 in the case of an error. Should this call succeed, then the same
 system calls are executed from a signal handler on each of the other