man7/nptl.7

   1 .\" Copyright (c) 2015 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\"
  26 .TH NPTL 7 2015-08-08 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 nptl \- Native POSIX Threads Library
  29 .SH DESCRIPTION
  30 NPTL (Native POSIX Threads Library)
  31 is the GNU C library POSIX threads implementation that is used on modern
  32 Linux systems.
  33 .\"
  34 .SS NPTL and signals
  35 NPTL makes internal use of the first two real-time signals
  36 (signal numbers 32 and 33).
  37 One of these signals is used to support thread cancellation and POSIX timers
  38 (see
  39 .BR timer_create (2));
  40 the other is used as part of a mechanism that ensures all threads in
  41 a process always have the same UIDs and GIDs, as required by POSIX.
  42 These signals cannot be used in applications.
  43 .PP
  44 To prevent accidental use of these signals in applications,
  45 which might interfere with the operation of the NPTL implementation,
  46 various glibc library functions and system call wrapper functions
  47 attempt to hide these signals from applications,
  48 as follows:
  49 .IP * 3
  50 .B SIGRTMIN
  51 is defined with the value 34 (rather than 32).
  52 .IP *
  53 The
  54 .BR sigwaitinfo (2),
  55 .BR sigtimedwait (2),
  56 and
  57 .BR sigwait (3)
  58 interfaces silently ignore requests to wait for these two signals
  59 if they are specified in the signal set argument of these calls.
  60 .IP *
  61 The
  62 .BR sigprocmask (2)
  63 and
  64 .BR pthread_sigmask (3)
  65 interfaces silently ignore attempts to block these two signals.
  66 .IP *
  67 The
  68 .BR sigaction (2),
  69 .BR pthread_kill (3),
  70 and
  71 .BR pthread_sigqueue (3)
  72 interfaces fail with the error
  73 .B EINVAL
  74 (indicating an invalid signal number) if these signals are specified.
  75 .IP *
  76 .BR sigfillset (3)
  77 does not include these two signals when it creates a full signal set.
  78 .\"
  79 .SS NPTL and process credential changes
  80 At the Linux kernel level,
  81 credentials (user and group IDs) are a per-thread attribute.
  82 However, POSIX requires that all of the POSIX threads in a process
  83 have the same credentials.
  84 To accommodate this requirement,
  85 the NPTL implementation wraps all of the system calls that
  86 change process credentials with functions that,
  87 in addition to invoking the underlying system call,
  88 arrange for all other threads in the process to also change their credentials.
  89 .PP
  90 The implementation of each of these system calls involves the use of
  91 a real-time signal that is sent (using
  92 .BR tgkill (2))
  93 to each of the other threads that must change its credentials.
  94 Before sending these signals, the thread that is changing credentials
  95 saves the new credential(s) and records the system call being employed
  96 in a global buffer.
  97 A signal handler in the receiving thread(s) fetches this information and
  98 then uses the same system call to change its credentials.
  99 .PP
 100 Wrapper functions employing this technique are provided for
 101 .BR setgid (2),
 102 .BR setuid (2),
 103 .BR setegid (2),
 104 .BR seteuid (2),
 105 .BR setregid (2),
 106 .BR setreuid (2),
 107 .BR setresgid (2),
 108 .BR setresuid (2),
 109 and
 110 .BR setgroups (2).
 111 .\" FIXME .
 112 .\" Maybe say something about vfork() not being serialized wrt set*id() APIs?
 113 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14749
 114 .SH CONFORMING TO
 115 For details of the conformance of NPTL to the POSIX standard, see
 116 .BR pthreads (7).
 117 .SH NOTES
 118 POSIX says
 119 .\" See POSIX.1-2008 specification of pthread_mutexattr_init()
 120 that any thread in any process with access to the memory
 121 containing a process-shared
 122 .RB ( PTHREAD_PROCESS_SHARED )
 123 mutex can operate on that mutex.
 124 However, on 64-bit x86 systems, the mutex definition for x86-64
 125 is incompatible with the mutex definition for i386,
 126 .\" See sysdeps/x86/bits/pthreadtypes.h
 127 meaning that 32-bit and 64-bit binaries can't share mutexes on x86-64 systems.
 128 .SH SEE ALSO
 129 .BR credentials (7),
 130 .BR pthreads (7),
 131 .BR signal (7),
 132 .BR standards (7)