man7/pthreads.7

   1 '\" t
   2 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   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.
  17 .\"
  18 .\" Formatted or processed versions of this manual, if unaccompanied by
  19 .\" the source, must acknowledge the copyright and authors of this work.
  20 .\"
  21 .TH PTHREADS 7  2005-06-07 "Linux" "Linux Programmer's Manual"
  22 .SH NAME
  23 pthreads \- POSIX threads
  24 .SH DESCRIPTION
  25 POSIX.1 specifies a set of interfaces (functions, header files) for
  26 threaded programming commonly known as POSIX threads, or Pthreads.
  27 A single process can contain multiple threads,
  28 all of which are executing the same program.
  29 These threads share the same global memory (data and heap segments),
  30 but each thread has its own stack (automatic variables).
  31
  32 POSIX.1 also requires that threads share a range of other attributes
  33 (i.e., these attributes are process-wide rather than per-thread):
  34 .IP \- 3
  35 process ID
  36 .IP \- 3
  37 parent process ID
  38 .IP \- 3
  39 process group ID and session ID
  40 .IP \- 3
  41 controlling terminal
  42 .IP \- 3
  43 user and group IDs
  44 .IP \- 3
  45 open file descriptors
  46 .IP \- 3
  47 record locks (see
  48 .BR fcntl (2))
  49 .IP \- 3
  50 signal dispositions
  51 .IP \- 3
  52 file mode creation mask
  53 .RB ( umask (2))
  54 .IP \- 3
  55 current directory
  56 .RB ( chdir (2))
  57 and
  58 root directory
  59 .RB ( chroot (2))
  60 .IP \- 3
  61 interval timers
  62 .RB ( setitimer (2))
  63 and POSIX timers
  64 .RB ( timer_create (3))
  65 .IP \- 3
  66 nice value
  67 .RB ( setpriority (2))
  68 .IP \- 3
  69 resource limits
  70 .RB ( setrlimit (2))
  71 .IP \- 3
  72 measurements of the consumption of CPU time
  73 .RB ( times (2))
  74 and resources
  75 .RB ( getrusage (2))
  76 .PP
  77 As well as the stack, POSIX.1 specifies that various other
  78 attributes are distinct for each thread, including:
  79 .IP \- 3
  80 thread ID (the
  81 .I pthread_t
  82 data type)
  83 .IP \- 3
  84 signal mask
  85 .RB ( pthread_sigmask (3))
  86 .IP \- 3
  87 the
  88 .I errno
  89 variable
  90 .IP \- 3
  91 alternate signal stack
  92 .RB ( sigaltstack (2))
  93 .IP \- 3
  94 real-time scheduling policy and priority
  95 .RB ( sched_setscheduler (2)
  96 and
  97 .BR sched_setparam (2))
  98 .PP
  99 The following Linux-specific features are also per-thread:
 100 .IP \- 3
 101 capabilities (see
 102 .BR capabilities (7))
 103 .IP \- 3
 104 CPU affinity
 105 .RB ( sched_setaffinity (2))
 106 .SS "Compiling on Linux"
 107 On Linux, programs that use the Pthreads API should be compiled using
 108 .IR "cc \-pthread" .
 109 .SS "Linux Implementations of POSIX Threads"
 110 Over time, two threading implementations have been provided by
 111 the GNU C library on Linux:
 112 .IP \- 3
 113 .B LinuxThreads
 114 This is the original Pthreads implementation.
 115 Since glibc 2.4, this implementation is no longer supported.
 116 .IP \- 3
 117 .B NPTL
 118 (Native POSIX Threads Library)
 119 This is the modern Pthreads implementation.
 120 By comparison with LinuxThreads, NPTL provides closer conformance to
 121 the requirements of the POSIX.1 specification and better performance
 122 when creating large numbers of threads.
 123 NPTL is available since glibc 2.3.2,
 124 and requires features that are present in the Linux 2.6 kernel.
 125 .PP
 126 Both of these are so-called 1:1 implementations, meaning that each
 127 thread maps to a kernel scheduling entity.
 128
 129 Both threading implementations employ the Linux
 130 .BR clone (2)
 131 system call.
 132 In NPTL, thread synchronization primitives (mutexes,
 133 thread joining, etc.) are implemented using the Linux
 134 .BR futex (2)
 135 system call.
 136 .SS LinuxThreads
 137 The notable features of this implementation are the following:
 138 .IP \- 3
 139 In addition to the main (initial) thread,
 140 and the threads that the program creates using
 141 .BR pthread_create (3),
 142 the implementation creates a "manager" thread.
 143 This thread handles thread creation and termination.
 144 (Problems can result if this thread is inadvertently killed.)
 145 .IP \- 3
 146 Signals are used internally by the implementation.
 147 On Linux 2.2 and later, the first three real-time signals are used.
 148 On older Linux kernels,
 149 .B SIGUSR1
 150 and
 151 .B SIGUSR2
 152 are used.
 153 Applications must avoid the use of whichever set of signals is
 154 employed by the implementation.
 155 .IP \- 3
 156 Threads do not share process IDs.
 157 (In effect, LinuxThreads threads are implemented as processes which share
 158 more information than usual, but which do not share a common process ID.)
 159 LinuxThreads threads (including the manager thread)
 160 are visible as separate processes using
 161 .BR ps (1).
 162 .PP
 163 The LinuxThreads implementation deviates from the POSIX.1
 164 specification in a number of ways, including the following:
 165 .IP \- 3
 166 Calls to
 167 .BR getpid (2)
 168 return a different value in each thread.
 169 .IP \- 3
 170 Calls to
 171 .BR getppid (2)
 172 in threads other than the main thread return the process ID of the
 173 manager thread; instead
 174 .BR getppid (2)
 175 in these threads should return the same value as
 176 .BR getppid (2)
 177 in the main thread.
 178 .IP \- 3
 179 When one thread creates a new child process using
 180 .BR fork (2),
 181 any thread should be able to
 182 .BR wait (2)
 183 on the child.
 184 However, the implementation only allows the thread that
 185 created the child to
 186 .BR wait (2)
 187 on it.
 188 .IP \- 3
 189 When a thread calls
 190 .BR execve (2),
 191 all other threads are terminated (as required by POSIX.1).
 192 However, the resulting process has the same PID as the thread that called
 193 .BR execve (2):
 194 it should have the same PID as the main thread.
 195 .IP \- 3
 196 Threads do not share user and group IDs.
 197 This can cause complications with set-user-ID programs and
 198 can cause failures in Pthreads functions if an application
 199 changes its credentials using
 200 .BR seteuid (2)
 201 or similar.
 202 .IP \- 3
 203 Threads do not share a common session ID and process group ID.
 204 .IP \- 3
 205 Threads do not share record locks created using
 206 .BR fcntl (2).
 207 .IP \- 3
 208 The information returned by
 209 .BR times (2)
 210 and
 211 .BR getrusage (2)
 212 is per-thread rather than process-wide.
 213 .IP \- 3
 214 Threads do not share semaphore undo values (see
 215 .BR semop (2)).
 216 .IP \- 3
 217 Threads do not share interval timers.
 218 .IP \- 3
 219 Threads do not share a common nice value.
 220 .IP \- 3
 221 POSIX.1 distinguishes the notions of signals that are directed
 222 to the process as a whole and signals are directed to individual
 223 threads.
 224 According to POSIX.1, a process-directed signal (sent using
 225 .BR kill (2),
 226 for example) should be handled by a single,
 227 arbitrarily selected thread within the process.
 228 LinuxThreads does not support the notion of process-directed signals:
 229 signals may only be sent to specific threads.
 230 .IP \- 3
 231 Threads have distinct alternate signal stack settings.
 232 However, a new thread's alternate signal stack settings
 233 are copied from the thread that created it, so that
 234 the threads initially share an alternate signal stack.
 235 (A new thread should start with no alternate signal stack defined.
 236 If two threads handle signals on their shared alternate signal
 237 stack at the same time, unpredictable program failures are
 238 likely to occur.)
 239 .SS NPTL
 240 With NPTL, all of the threads in a process are placed
 241 in the same thread group;
 242 all members of a thread groups share the same PID.
 243 NPTL does not employ a manager thread.
 244 NPTL makes internal use of the first two real-time signals;
 245 these signals cannot be used in applications.
 246
 247 NPTL still has a few non-conformances with POSIX.1:
 248 .IP \- 3
 249 Threads do not share a common nice value.
 250 .\" FIXME . bug report filed for NPTL nice non-conformance
 251 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258
 252 .PP
 253 Some NPTL non-conformances only occur with older kernels:
 254 .IP \- 3
 255 The information returned by
 256 .BR times (2)
 257 and
 258 .BR getrusage (2)
 259 is per-thread rather than process-wide (fixed in kernel 2.6.9).
 260 .IP \- 3
 261 Threads do not share resource limits (fixed in kernel 2.6.10).
 262 .IP \- 3
 263 Threads do not share interval timers (fixed in kernel 2.6.12).
 264 .IP \- 3
 265 Only the main thread is permitted to start a new session using
 266 .BR setsid (2)
 267 (fixed in kernel 2.6.16).
 268 .IP \- 3
 269 Only the main thread is permitted to make the process into a
 270 process group leader using
 271 .BR setpgid (2)
 272 (fixed in kernel 2.6.16).
 273 .IP \- 3
 274 Threads have distinct alternate signal stack settings.
 275 However, a new thread's alternate signal stack settings
 276 are copied from the thread that created it, so that
 277 the threads initially share an alternate signal stack
 278 (fixed in kernel 2.6.16).
 279 .PP
 280 Note the following further points about the NPTL implementation:
 281 .IP \- 3
 282 If the stack size soft resource limit (see the description of
 283 .B RLIMIT_STACK
 284 in
 285 .BR setrlimit (2))
 286 is set to a value other than
 287 .IR unlimited ,
 288 then this value defines the default stack size for new threads.
 289 To be effective, this limit must be set before the program
 290 is executed, perhaps using the
 291 .I ulimit -s
 292 shell built-in command
 293 .RI ( "limit stacksize"
 294 in the C shell).
 295 .SS "Determining the Threading Implementation"
 296 Since glibc 2.3.2, the
 297 .BR getconf (1)
 298 command can be used to determine
 299 the system's threading implementation, for example:
 300 .nf
 301 .in +4
 302
 303 bash$ getconf GNU_LIBPTHREAD_VERSION
 304 NPTL 2.3.4
 305 .in -4
 306 .fi
 307 .PP
 308 With older glibc versions, a command such as the following should
 309 be sufficient to determine the default threading implementation:
 310 .nf
 311 .in +4
 312
 313 bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \\
 314                 egrep \-i 'threads|ntpl'
 315         Native POSIX Threads Library by Ulrich Drepper et al
 316 .in -4
 317 .fi
 318 .SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL"
 319 On systems with a glibc that supports both LinuxThreads and NPTL
 320 (i.e., glibc 2.3.\fIx\fP), the
 321 .B LD_ASSUME_KERNEL
 322 environment variable can be used to override
 323 the dynamic linker's default choice of threading implementation.
 324 This variable tells the dynamic linker to assume that it is
 325 running on top of a particular kernel version.
 326 By specifying a kernel version that does not
 327 provide the support required by NPTL, we can force the use
 328 of LinuxThreads.
 329 (The most likely reason for doing this is to run a
 330 (broken) application that depends on some non-conformant behavior
 331 in LinuxThreads.)
 332 For example:
 333 .nf
 334 .in +4
 335
 336 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\
 337                 awk '{print $3}' ) | egrep \-i 'threads|ntpl'
 338         linuxthreads-0.10 by Xavier Leroy
 339 .in -4
 340 .fi
 341 .SH "SEE ALSO"
 342 .BR clone (2),
 343 .BR futex (2),
 344 .BR gettid (2),
 345 .BR futex (7),
 346 and various Pthreads manual pages, for example:
 347 .BR pthread_atfork (3),
 348 .BR pthread_cleanup_push (3),
 349 .BR pthread_cond_signal (3),
 350 .BR pthread_cond_wait (3),
 351 .BR pthread_create (3),
 352 .BR pthread_detach (3),
 353 .BR pthread_equal (3),
 354 .BR pthread_exit (3),
 355 .BR pthread_key_create (3),
 356 .BR pthread_kill (3),
 357 .BR pthread_mutex_lock (3),
 358 .BR pthread_mutex_unlock (3),
 359 .BR pthread_once (3),
 360 .BR pthread_setcancelstate (3),
 361 .BR pthread_setcanceltype (3),
 362 .BR pthread_setspecific (3),
 363 .BR pthread_sigmask (3),
 364 and
 365 .BR pthread_testcancel (3).