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.  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 .\"
  24 .TH PTHREADS 7  2008-05-29 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 pthreads \- POSIX threads
  27 .SH DESCRIPTION
  28 POSIX.1 specifies a set of interfaces (functions, header files) for
  29 threaded programming commonly known as POSIX threads, or Pthreads.
  30 A single process can contain multiple threads,
  31 all of which are executing the same program.
  32 These threads share the same global memory (data and heap segments),
  33 but each thread has its own stack (automatic variables).
  34
  35 POSIX.1 also requires that threads share a range of other attributes
  36 (i.e., these attributes are process-wide rather than per-thread):
  37 .IP \- 3
  38 process ID
  39 .IP \- 3
  40 parent process ID
  41 .IP \- 3
  42 process group ID and session ID
  43 .IP \- 3
  44 controlling terminal
  45 .IP \- 3
  46 user and group IDs
  47 .IP \- 3
  48 open file descriptors
  49 .IP \- 3
  50 record locks (see
  51 .BR fcntl (2))
  52 .IP \- 3
  53 signal dispositions
  54 .IP \- 3
  55 file mode creation mask
  56 .RB ( umask (2))
  57 .IP \- 3
  58 current directory
  59 .RB ( chdir (2))
  60 and
  61 root directory
  62 .RB ( chroot (2))
  63 .IP \- 3
  64 interval timers
  65 .RB ( setitimer (2))
  66 and POSIX timers
  67 .RB ( timer_create (3))
  68 .IP \- 3
  69 nice value
  70 .RB ( setpriority (2))
  71 .IP \- 3
  72 resource limits
  73 .RB ( setrlimit (2))
  74 .IP \- 3
  75 measurements of the consumption of CPU time
  76 .RB ( times (2))
  77 and resources
  78 .RB ( getrusage (2))
  79 .PP
  80 As well as the stack, POSIX.1 specifies that various other
  81 attributes are distinct for each thread, including:
  82 .IP \- 3
  83 thread ID (the
  84 .I pthread_t
  85 data type)
  86 .IP \- 3
  87 signal mask
  88 .RB ( pthread_sigmask (3))
  89 .IP \- 3
  90 the
  91 .I errno
  92 variable
  93 .IP \- 3
  94 alternate signal stack
  95 .RB ( sigaltstack (2))
  96 .IP \- 3
  97 real-time scheduling policy and priority
  98 .RB ( sched_setscheduler (2)
  99 and
 100 .BR sched_setparam (2))
 101 .PP
 102 The following Linux-specific features are also per-thread:
 103 .IP \- 3
 104 capabilities (see
 105 .BR capabilities (7))
 106 .IP \- 3
 107 CPU affinity
 108 .RB ( sched_setaffinity (2))
 109 .SS "Thread-safe functions"
 110 A thread-safe function is one that can be safely
 111 (i.e., it will deliver the same results regardless of whether it is)
 112 called from multiple threads at the same time.
 113
 114 POSIX.1-2001 requires that all functions specified in the standard
 115 shall be thread-safe, except for the following functions:
 116 .\" FIXME . SUSv4 removes ecvt(), fcvt(), gcvt(), gethostbyname(), and
 117 .\" gethostbyaddr(), since they are removed from the standard, and
 118 .\" and adds strerror() and system().
 119 .in +4n
 120 .nf
 121
 122 asctime()
 123 basename()
 124 catgets()
 125 crypt()
 126 ctermid() if passed a non-NULL argument
 127 ctime()
 128 dbm_clearerr()
 129 dbm_close()
 130 dbm_delete()
 131 dbm_error()
 132 dbm_fetch()
 133 dbm_firstkey()
 134 dbm_nextkey()
 135 dbm_open()
 136 dbm_store()
 137 dirname()
 138 dlerror()
 139 drand48()
 140 ecvt()
 141 encrypt()
 142 endgrent()
 143 endpwent()
 144 endutxent()
 145 fcvt()
 146 ftw()
 147 gcvt()
 148 getc_unlocked()
 149 getchar_unlocked()
 150 getdate()
 151 getenv()
 152 getgrent()
 153 getgrgid()
 154 getgrnam()
 155 gethostbyaddr()
 156 gethostbyname()
 157 gethostent()
 158 getlogin()
 159 getnetbyaddr()
 160 getnetbyname()
 161 getnetent()
 162 getopt()
 163 getprotobyname()
 164 getprotobynumber()
 165 getprotoent()
 166 getpwent()
 167 getpwnam()
 168 getpwuid()
 169 getservbyname()
 170 getservbyport()
 171 getservent()
 172 getutxent()
 173 getutxid()
 174 getutxline()
 175 gmtime()
 176 hcreate()
 177 hdestroy()
 178 hsearch()
 179 inet_ntoa()
 180 l64a()
 181 lgamma()
 182 lgammaf()
 183 lgammal()
 184 localeconv()
 185 localtime()
 186 lrand48()
 187 mrand48()
 188 nftw()
 189 nl_langinfo()
 190 ptsname()
 191 putc_unlocked()
 192 putchar_unlocked()
 193 putenv()
 194 pututxline()
 195 rand()
 196 readdir()
 197 setenv()
 198 setgrent()
 199 setkey()
 200 setpwent()
 201 setutxent()
 202 strerror()
 203 strtok()
 204 tmpnam() if passed a non-NULL argument
 205 ttyname()
 206 unsetenv()
 207 wcrtomb() if its final argument is NULL
 208 wcsrtombs() if its final argument is NULL
 209 wcstombs()
 210 wctomb()
 211 .fi
 212 .in
 213 .SS "Compiling on Linux"
 214 On Linux, programs that use the Pthreads API should be compiled using
 215 .IR "cc \-pthread" .
 216 .SS "Linux Implementations of POSIX Threads"
 217 Over time, two threading implementations have been provided by
 218 the GNU C library on Linux:
 219 .TP
 220 .B LinuxThreads
 221 This is the original Pthreads implementation.
 222 Since glibc 2.4, this implementation is no longer supported.
 223 .TP
 224 .BR NPTL " (Native POSIX Threads Library)"
 225 This is the modern Pthreads implementation.
 226 By comparison with LinuxThreads, NPTL provides closer conformance to
 227 the requirements of the POSIX.1 specification and better performance
 228 when creating large numbers of threads.
 229 NPTL is available since glibc 2.3.2,
 230 and requires features that are present in the Linux 2.6 kernel.
 231 .PP
 232 Both of these are so-called 1:1 implementations, meaning that each
 233 thread maps to a kernel scheduling entity.
 234 Both threading implementations employ the Linux
 235 .BR clone (2)
 236 system call.
 237 In NPTL, thread synchronization primitives (mutexes,
 238 thread joining, etc.) are implemented using the Linux
 239 .BR futex (2)
 240 system call.
 241 .SS LinuxThreads
 242 The notable features of this implementation are the following:
 243 .IP \- 3
 244 In addition to the main (initial) thread,
 245 and the threads that the program creates using
 246 .BR pthread_create (3),
 247 the implementation creates a "manager" thread.
 248 This thread handles thread creation and termination.
 249 (Problems can result if this thread is inadvertently killed.)
 250 .IP \- 3
 251 Signals are used internally by the implementation.
 252 On Linux 2.2 and later, the first three real-time signals are used.
 253 On older Linux kernels,
 254 .B SIGUSR1
 255 and
 256 .B SIGUSR2
 257 are used.
 258 Applications must avoid the use of whichever set of signals is
 259 employed by the implementation.
 260 .IP \- 3
 261 Threads do not share process IDs.
 262 (In effect, LinuxThreads threads are implemented as processes which share
 263 more information than usual, but which do not share a common process ID.)
 264 LinuxThreads threads (including the manager thread)
 265 are visible as separate processes using
 266 .BR ps (1).
 267 .PP
 268 The LinuxThreads implementation deviates from the POSIX.1
 269 specification in a number of ways, including the following:
 270 .IP \- 3
 271 Calls to
 272 .BR getpid (2)
 273 return a different value in each thread.
 274 .IP \- 3
 275 Calls to
 276 .BR getppid (2)
 277 in threads other than the main thread return the process ID of the
 278 manager thread; instead
 279 .BR getppid (2)
 280 in these threads should return the same value as
 281 .BR getppid (2)
 282 in the main thread.
 283 .IP \- 3
 284 When one thread creates a new child process using
 285 .BR fork (2),
 286 any thread should be able to
 287 .BR wait (2)
 288 on the child.
 289 However, the implementation only allows the thread that
 290 created the child to
 291 .BR wait (2)
 292 on it.
 293 .IP \- 3
 294 When a thread calls
 295 .BR execve (2),
 296 all other threads are terminated (as required by POSIX.1).
 297 However, the resulting process has the same PID as the thread that called
 298 .BR execve (2):
 299 it should have the same PID as the main thread.
 300 .IP \- 3
 301 Threads do not share user and group IDs.
 302 This can cause complications with set-user-ID programs and
 303 can cause failures in Pthreads functions if an application
 304 changes its credentials using
 305 .BR seteuid (2)
 306 or similar.
 307 .IP \- 3
 308 Threads do not share a common session ID and process group ID.
 309 .IP \- 3
 310 Threads do not share record locks created using
 311 .BR fcntl (2).
 312 .IP \- 3
 313 The information returned by
 314 .BR times (2)
 315 and
 316 .BR getrusage (2)
 317 is per-thread rather than process-wide.
 318 .IP \- 3
 319 Threads do not share semaphore undo values (see
 320 .BR semop (2)).
 321 .IP \- 3
 322 Threads do not share interval timers.
 323 .IP \- 3
 324 Threads do not share a common nice value.
 325 .IP \- 3
 326 POSIX.1 distinguishes the notions of signals that are directed
 327 to the process as a whole and signals that are directed to individual
 328 threads.
 329 According to POSIX.1, a process-directed signal (sent using
 330 .BR kill (2),
 331 for example) should be handled by a single,
 332 arbitrarily selected thread within the process.
 333 LinuxThreads does not support the notion of process-directed signals:
 334 signals may only be sent to specific threads.
 335 .IP \- 3
 336 Threads have distinct alternate signal stack settings.
 337 However, a new thread's alternate signal stack settings
 338 are copied from the thread that created it, so that
 339 the threads initially share an alternate signal stack.
 340 (A new thread should start with no alternate signal stack defined.
 341 If two threads handle signals on their shared alternate signal
 342 stack at the same time, unpredictable program failures are
 343 likely to occur.)
 344 .SS NPTL
 345 With NPTL, all of the threads in a process are placed
 346 in the same thread group;
 347 all members of a thread groups share the same PID.
 348 NPTL does not employ a manager thread.
 349 NPTL makes internal use of the first two real-time signals;
 350 these signals cannot be used in applications.
 351
 352 NPTL still has at least one non-conformance with POSIX.1:
 353 .IP \- 3
 354 Threads do not share a common nice value.
 355 .\" FIXME . bug report filed for NPTL nice non-conformance
 356 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258
 357 .PP
 358 Some NPTL non-conformances only occur with older kernels:
 359 .IP \- 3
 360 The information returned by
 361 .BR times (2)
 362 and
 363 .BR getrusage (2)
 364 is per-thread rather than process-wide (fixed in kernel 2.6.9).
 365 .IP \- 3
 366 Threads do not share resource limits (fixed in kernel 2.6.10).
 367 .IP \- 3
 368 Threads do not share interval timers (fixed in kernel 2.6.12).
 369 .IP \- 3
 370 Only the main thread is permitted to start a new session using
 371 .BR setsid (2)
 372 (fixed in kernel 2.6.16).
 373 .IP \- 3
 374 Only the main thread is permitted to make the process into a
 375 process group leader using
 376 .BR setpgid (2)
 377 (fixed in kernel 2.6.16).
 378 .IP \- 3
 379 Threads have distinct alternate signal stack settings.
 380 However, a new thread's alternate signal stack settings
 381 are copied from the thread that created it, so that
 382 the threads initially share an alternate signal stack
 383 (fixed in kernel 2.6.16).
 384 .PP
 385 Note the following further points about the NPTL implementation:
 386 .IP \- 3
 387 If the stack size soft resource limit (see the description of
 388 .B RLIMIT_STACK
 389 in
 390 .BR setrlimit (2))
 391 is set to a value other than
 392 .IR unlimited ,
 393 then this value defines the default stack size for new threads.
 394 To be effective, this limit must be set before the program
 395 is executed, perhaps using the
 396 .I ulimit -s
 397 shell built-in command
 398 .RI ( "limit stacksize"
 399 in the C shell).
 400 .SS "Determining the Threading Implementation"
 401 Since glibc 2.3.2, the
 402 .BR getconf (1)
 403 command can be used to determine
 404 the system's threading implementation, for example:
 405 .nf
 406 .in +4n
 407
 408 bash$ getconf GNU_LIBPTHREAD_VERSION
 409 NPTL 2.3.4
 410 .in
 411 .fi
 412 .PP
 413 With older glibc versions, a command such as the following should
 414 be sufficient to determine the default threading implementation:
 415 .nf
 416 .in +4n
 417
 418 bash$ $( ldd /bin/ls | grep libc.so | awk \(aq{print $3}\(aq ) | \\
 419                 egrep \-i \(aqthreads|nptl\(aq
 420         Native POSIX Threads Library by Ulrich Drepper et al
 421 .in
 422 .fi
 423 .SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL"
 424 On systems with a glibc that supports both LinuxThreads and NPTL
 425 (i.e., glibc 2.3.\fIx\fP), the
 426 .B LD_ASSUME_KERNEL
 427 environment variable can be used to override
 428 the dynamic linker's default choice of threading implementation.
 429 This variable tells the dynamic linker to assume that it is
 430 running on top of a particular kernel version.
 431 By specifying a kernel version that does not
 432 provide the support required by NPTL, we can force the use
 433 of LinuxThreads.
 434 (The most likely reason for doing this is to run a
 435 (broken) application that depends on some non-conformant behavior
 436 in LinuxThreads.)
 437 For example:
 438 .nf
 439 .in +4n
 440
 441 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\
 442                 awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|ntpl\(aq
 443         linuxthreads-0.10 by Xavier Leroy
 444 .in
 445 .fi
 446 .SH "SEE ALSO"
 447 .BR clone (2),
 448 .BR futex (2),
 449 .BR gettid (2),
 450 .BR futex (7),
 451 and various Pthreads manual pages, for example:
 452 .BR pthread_atfork (3),
 453 .BR pthread_cleanup_push (3),
 454 .BR pthread_cond_signal (3),
 455 .BR pthread_cond_wait (3),
 456 .BR pthread_create (3),
 457 .BR pthread_detach (3),
 458 .BR pthread_equal (3),
 459 .BR pthread_exit (3),
 460 .BR pthread_key_create (3),
 461 .BR pthread_kill (3),
 462 .BR pthread_mutex_lock (3),
 463 .BR pthread_mutex_unlock (3),
 464 .BR pthread_once (3),
 465 .BR pthread_setcancelstate (3),
 466 .BR pthread_setcanceltype (3),
 467 .BR pthread_setspecific (3),
 468 .BR pthread_sigmask (3),
 469 and
 470 .BR pthread_testcancel (3).