1 files changed, 112 insertions, 0 deletions
diff --git a/man/man7/nptl.7 b/man/man7/nptl.7
new file mode 100644
index 000000000..1bff274d3
--- /dev/null
+++ b/man/man7/nptl.7
@@ -0,0 +1,112 @@
+.\" Copyright (c) 2015 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH nptl 7 (date) "Linux man-pages (unreleased)"
+.SH NAME
+nptl \- Native POSIX Threads Library
+.SH DESCRIPTION
+NPTL (Native POSIX Threads Library)
+is the GNU C library POSIX threads implementation that is used on modern
+Linux systems.
+.\"
+.SS NPTL and signals
+NPTL makes internal use of the first two real-time signals
+(signal numbers 32 and 33).
+One of these signals is used to support thread cancelation and POSIX timers
+(see
+.BR timer_create (2));
+the other is used as part of a mechanism that ensures all threads in
+a process always have the same UIDs and GIDs, as required by POSIX.
+These signals cannot be used in applications.
+.P
+To prevent accidental use of these signals in applications,
+which might interfere with the operation of the NPTL implementation,
+various glibc library functions and system call wrapper functions
+attempt to hide these signals from applications,
+as follows:
+.IP \[bu] 3
+.B SIGRTMIN
+is defined with the value 34 (rather than 32).
+.IP \[bu]
+The
+.BR sigwaitinfo (2),
+.BR sigtimedwait (2),
+and
+.BR sigwait (3)
+interfaces silently ignore requests to wait for these two signals
+if they are specified in the signal set argument of these calls.
+.IP \[bu]
+The
+.BR sigprocmask (2)
+and
+.BR pthread_sigmask (3)
+interfaces silently ignore attempts to block these two signals.
+.IP \[bu]
+The
+.BR sigaction (2),
+.BR pthread_kill (3),
+and
+.BR pthread_sigqueue (3)
+interfaces fail with the error
+.B EINVAL
+(indicating an invalid signal number) if these signals are specified.
+.IP \[bu]
+.BR sigfillset (3)
+does not include these two signals when it creates a full signal set.
+.\"
+.SS NPTL and process credential changes
+At the Linux kernel level,
+credentials (user and group IDs) are a per-thread attribute.
+However, POSIX requires that all of the POSIX threads in a process
+have the same credentials.
+To accommodate this requirement,
+the NPTL implementation wraps all of the system calls that
+change process credentials with functions that,
+in addition to invoking the underlying system call,
+arrange for all other threads in the process to also change their credentials.
+.P
+The implementation of each of these system calls involves the use of
+a real-time signal that is sent (using
+.BR tgkill (2))
+to each of the other threads that must change its credentials.
+Before sending these signals, the thread that is changing credentials
+saves the new credential(s) and records the system call being employed
+in a global buffer.
+A signal handler in the receiving thread(s) fetches this information and
+then uses the same system call to change its credentials.
+.P
+Wrapper functions employing this technique are provided for
+.BR setgid (2),
+.BR setuid (2),
+.BR setegid (2),
+.BR seteuid (2),
+.BR setregid (2),
+.BR setreuid (2),
+.BR setresgid (2),
+.BR setresuid (2),
+and
+.BR setgroups (2).
+.\" FIXME .
+.\" Maybe say something about vfork() not being serialized wrt set*id() APIs?
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14749
+.SH STANDARDS
+For details of the conformance of NPTL to the POSIX standard, see
+.BR pthreads (7).
+.SH NOTES
+POSIX says
+.\" See POSIX.1-2008 specification of pthread_mutexattr_init()
+that any thread in any process with access to the memory
+containing a process-shared
+.RB ( PTHREAD_PROCESS_SHARED )
+mutex can operate on that mutex.
+However, on 64-bit x86 systems, the mutex definition for x86-64
+is incompatible with the mutex definition for i386,
+.\" See sysdeps/x86/bits/pthreadtypes.h
+meaning that 32-bit and 64-bit binaries can't share mutexes on x86-64 systems.
+.SH SEE ALSO
+.BR credentials (7),
+.BR pthreads (7),
+.BR signal (7),
+.BR standards (7)