man7/pthreads.7

   1 '\" t
   2 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREADS 7  2019-03-06 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthreads \- POSIX threads
  29 .SH DESCRIPTION
  30 POSIX.1 specifies a set of interfaces (functions, header files) for
  31 threaded programming commonly known as POSIX threads, or Pthreads.
  32 A single process can contain multiple threads,
  33 all of which are executing the same program.
  34 These threads share the same global memory (data and heap segments),
  35 but each thread has its own stack (automatic variables).
  36 .PP
  37 POSIX.1 also requires that threads share a range of other attributes
  38 (i.e., these attributes are process-wide rather than per-thread):
  39 .IP \- 3
  40 process ID
  41 .IP \- 3
  42 parent process ID
  43 .IP \- 3
  44 process group ID and session ID
  45 .IP \- 3
  46 controlling terminal
  47 .IP \- 3
  48 user and group IDs
  49 .IP \- 3
  50 open file descriptors
  51 .IP \- 3
  52 record locks (see
  53 .BR fcntl (2))
  54 .IP \- 3
  55 signal dispositions
  56 .IP \- 3
  57 file mode creation mask
  58 .RB ( umask (2))
  59 .IP \- 3
  60 current directory
  61 .RB ( chdir (2))
  62 and
  63 root directory
  64 .RB ( chroot (2))
  65 .IP \- 3
  66 interval timers
  67 .RB ( setitimer (2))
  68 and POSIX timers
  69 .RB ( timer_create (2))
  70 .IP \- 3
  71 nice value
  72 .RB ( setpriority (2))
  73 .IP \- 3
  74 resource limits
  75 .RB ( setrlimit (2))
  76 .IP \- 3
  77 measurements of the consumption of CPU time
  78 .RB ( times (2))
  79 and resources
  80 .RB ( getrusage (2))
  81 .PP
  82 As well as the stack, POSIX.1 specifies that various other
  83 attributes are distinct for each thread, including:
  84 .IP \- 3
  85 thread ID (the
  86 .I pthread_t
  87 data type)
  88 .IP \- 3
  89 signal mask
  90 .RB ( pthread_sigmask (3))
  91 .IP \- 3
  92 the
  93 .I errno
  94 variable
  95 .IP \- 3
  96 alternate signal stack
  97 .RB ( sigaltstack (2))
  98 .IP \- 3
  99 real-time scheduling policy and priority
 100 .RB ( sched (7))
 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 Pthreads function return values
 110 Most pthreads functions return 0 on success, and an error number on failure.
 111 Note that the pthreads functions do not set
 112 .IR errno .
 113 For each of the pthreads functions that can return an error,
 114 POSIX.1-2001 specifies that the function can never fail with the error
 115 .BR EINTR .
 116 .SS Thread IDs
 117 Each of the threads in a process has a unique thread identifier
 118 (stored in the type
 119 .IR pthread_t ).
 120 This identifier is returned to the caller of
 121 .BR pthread_create (3),
 122 and a thread can obtain its own thread identifier using
 123 .BR pthread_self (3).
 124 .PP
 125 Thread IDs are guaranteed to be unique only within a process.
 126 (In all pthreads functions that accept a thread ID as an argument,
 127 that ID by definition refers to a thread in
 128 the same process as the caller.)
 129 .PP
 130 The system may reuse a thread ID after a terminated thread has been joined,
 131 or a detached thread has terminated.
 132 POSIX says: "If an application attempts to use a thread ID whose
 133 lifetime has ended, the behavior is undefined."
 134 .SS Thread-safe functions
 135 A thread-safe function is one that can be safely
 136 (i.e., it will deliver the same results regardless of whether it is)
 137 called from multiple threads at the same time.
 138 .PP
 139 POSIX.1-2001 and POSIX.1-2008 require that all functions specified
 140 in the standard shall be thread-safe,
 141 except for the following functions:
 142 .PP
 143 .in +4n
 144 .EX
 145 asctime()
 146 basename()
 147 catgets()
 148 crypt()
 149 ctermid() if passed a non-NULL argument
 150 ctime()
 151 dbm_clearerr()
 152 dbm_close()
 153 dbm_delete()
 154 dbm_error()
 155 dbm_fetch()
 156 dbm_firstkey()
 157 dbm_nextkey()
 158 dbm_open()
 159 dbm_store()
 160 dirname()
 161 dlerror()
 162 drand48()
 163 ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 164 encrypt()
 165 endgrent()
 166 endpwent()
 167 endutxent()
 168 fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 169 ftw()
 170 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 171 getc_unlocked()
 172 getchar_unlocked()
 173 getdate()
 174 getenv()
 175 getgrent()
 176 getgrgid()
 177 getgrnam()
 178 gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 179 gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 180 gethostent()
 181 getlogin()
 182 getnetbyaddr()
 183 getnetbyname()
 184 getnetent()
 185 getopt()
 186 getprotobyname()
 187 getprotobynumber()
 188 getprotoent()
 189 getpwent()
 190 getpwnam()
 191 getpwuid()
 192 getservbyname()
 193 getservbyport()
 194 getservent()
 195 getutxent()
 196 getutxid()
 197 getutxline()
 198 gmtime()
 199 hcreate()
 200 hdestroy()
 201 hsearch()
 202 inet_ntoa()
 203 l64a()
 204 lgamma()
 205 lgammaf()
 206 lgammal()
 207 localeconv()
 208 localtime()
 209 lrand48()
 210 mrand48()
 211 nftw()
 212 nl_langinfo()
 213 ptsname()
 214 putc_unlocked()
 215 putchar_unlocked()
 216 putenv()
 217 pututxline()
 218 rand()
 219 readdir()
 220 setenv()
 221 setgrent()
 222 setkey()
 223 setpwent()
 224 setutxent()
 225 strerror()
 226 strsignal() [Added in POSIX.1-2008]
 227 strtok()
 228 system() [Added in POSIX.1-2008]
 229 tmpnam() if passed a non-NULL argument
 230 ttyname()
 231 unsetenv()
 232 wcrtomb() if its final argument is NULL
 233 wcsrtombs() if its final argument is NULL
 234 wcstombs()
 235 wctomb()
 236 .EE
 237 .in
 238 .SS Async-cancel-safe functions
 239 An async-cancel-safe function is one that can be safely called
 240 in an application where asynchronous cancelability is enabled (see
 241 .BR pthread_setcancelstate (3)).
 242 .PP
 243 Only the following functions are required to be async-cancel-safe by
 244 POSIX.1-2001 and POSIX.1-2008:
 245 .PP
 246 .in +4n
 247 .EX
 248 pthread_cancel()
 249 pthread_setcancelstate()
 250 pthread_setcanceltype()
 251 .EE
 252 .in
 253 .SS Cancellation points
 254 POSIX.1 specifies that certain functions must,
 255 and certain other functions may, be cancellation points.
 256 If a thread is cancelable, its cancelability type is deferred,
 257 and a cancellation request is pending for the thread,
 258 then the thread is canceled when it calls a function
 259 that is a cancellation point.
 260 .PP
 261 The following functions are required to be cancellation points by
 262 POSIX.1-2001 and/or POSIX.1-2008:
 263 .PP
 264 .\" FIXME
 265 .\" Document the list of all functions that are cancellation points in glibc
 266 .in +4n
 267 .EX
 268 accept()
 269 aio_suspend()
 270 clock_nanosleep()
 271 close()
 272 connect()
 273 creat()
 274 fcntl() F_SETLKW
 275 fdatasync()
 276 fsync()
 277 getmsg()
 278 getpmsg()
 279 lockf() F_LOCK
 280 mq_receive()
 281 mq_send()
 282 mq_timedreceive()
 283 mq_timedsend()
 284 msgrcv()
 285 msgsnd()
 286 msync()
 287 nanosleep()
 288 open()
 289 openat() [Added in POSIX.1-2008]
 290 pause()
 291 poll()
 292 pread()
 293 pselect()
 294 pthread_cond_timedwait()
 295 pthread_cond_wait()
 296 pthread_join()
 297 pthread_testcancel()
 298 putmsg()
 299 putpmsg()
 300 pwrite()
 301 read()
 302 readv()
 303 recv()
 304 recvfrom()
 305 recvmsg()
 306 select()
 307 sem_timedwait()
 308 sem_wait()
 309 send()
 310 sendmsg()
 311 sendto()
 312 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
 313 sigsuspend()
 314 sigtimedwait()
 315 sigwait()
 316 sigwaitinfo()
 317 sleep()
 318 system()
 319 tcdrain()
 320 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
 321 wait()
 322 waitid()
 323 waitpid()
 324 write()
 325 writev()
 326 .EE
 327 .in
 328 .PP
 329 The following functions may be cancellation points according to
 330 POSIX.1-2001 and/or POSIX.1-2008:
 331 .PP
 332 .in +4n
 333 .EX
 334 access()
 335 asctime()
 336 asctime_r()
 337 catclose()
 338 catgets()
 339 catopen()
 340 chmod() [Added in POSIX.1-2008]
 341 chown() [Added in POSIX.1-2008]
 342 closedir()
 343 closelog()
 344 ctermid()
 345 ctime()
 346 ctime_r()
 347 dbm_close()
 348 dbm_delete()
 349 dbm_fetch()
 350 dbm_nextkey()
 351 dbm_open()
 352 dbm_store()
 353 dlclose()
 354 dlopen()
 355 dprintf() [Added in POSIX.1-2008]
 356 endgrent()
 357 endhostent()
 358 endnetent()
 359 endprotoent()
 360 endpwent()
 361 endservent()
 362 endutxent()
 363 faccessat() [Added in POSIX.1-2008]
 364 fchmod() [Added in POSIX.1-2008]
 365 fchmodat() [Added in POSIX.1-2008]
 366 fchown() [Added in POSIX.1-2008]
 367 fchownat() [Added in POSIX.1-2008]
 368 fclose()
 369 fcntl() (for any value of cmd argument)
 370 fflush()
 371 fgetc()
 372 fgetpos()
 373 fgets()
 374 fgetwc()
 375 fgetws()
 376 fmtmsg()
 377 fopen()
 378 fpathconf()
 379 fprintf()
 380 fputc()
 381 fputs()
 382 fputwc()
 383 fputws()
 384 fread()
 385 freopen()
 386 fscanf()
 387 fseek()
 388 fseeko()
 389 fsetpos()
 390 fstat()
 391 fstatat() [Added in POSIX.1-2008]
 392 ftell()
 393 ftello()
 394 ftw()
 395 futimens() [Added in POSIX.1-2008]
 396 fwprintf()
 397 fwrite()
 398 fwscanf()
 399 getaddrinfo()
 400 getc()
 401 getc_unlocked()
 402 getchar()
 403 getchar_unlocked()
 404 getcwd()
 405 getdate()
 406 getdelim() [Added in POSIX.1-2008]
 407 getgrent()
 408 getgrgid()
 409 getgrgid_r()
 410 getgrnam()
 411 getgrnam_r()
 412 gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]
 413 gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]
 414 gethostent()
 415 gethostid()
 416 gethostname()
 417 getline() [Added in POSIX.1-2008]
 418 getlogin()
 419 getlogin_r()
 420 getnameinfo()
 421 getnetbyaddr()
 422 getnetbyname()
 423 getnetent()
 424 getopt() (if opterr is nonzero)
 425 getprotobyname()
 426 getprotobynumber()
 427 getprotoent()
 428 getpwent()
 429 getpwnam()
 430 getpwnam_r()
 431 getpwuid()
 432 getpwuid_r()
 433 gets()
 434 getservbyname()
 435 getservbyport()
 436 getservent()
 437 getutxent()
 438 getutxid()
 439 getutxline()
 440 getwc()
 441 getwchar()
 442 getwd() [SUSv3 only (function removed in POSIX.1-2008)]
 443 glob()
 444 iconv_close()
 445 iconv_open()
 446 ioctl()
 447 link()
 448 linkat() [Added in POSIX.1-2008]
 449 lio_listio() [Added in POSIX.1-2008]
 450 localtime()
 451 localtime_r()
 452 lockf() [Added in POSIX.1-2008]
 453 lseek()
 454 lstat()
 455 mkdir() [Added in POSIX.1-2008]
 456 mkdirat() [Added in POSIX.1-2008]
 457 mkdtemp() [Added in POSIX.1-2008]
 458 mkfifo() [Added in POSIX.1-2008]
 459 mkfifoat() [Added in POSIX.1-2008]
 460 mknod() [Added in POSIX.1-2008]
 461 mknodat() [Added in POSIX.1-2008]
 462 mkstemp()
 463 mktime()
 464 nftw()
 465 opendir()
 466 openlog()
 467 pathconf()
 468 pclose()
 469 perror()
 470 popen()
 471 posix_fadvise()
 472 posix_fallocate()
 473 posix_madvise()
 474 posix_openpt()
 475 posix_spawn()
 476 posix_spawnp()
 477 posix_trace_clear()
 478 posix_trace_close()
 479 posix_trace_create()
 480 posix_trace_create_withlog()
 481 posix_trace_eventtypelist_getnext_id()
 482 posix_trace_eventtypelist_rewind()
 483 posix_trace_flush()
 484 posix_trace_get_attr()
 485 posix_trace_get_filter()
 486 posix_trace_get_status()
 487 posix_trace_getnext_event()
 488 posix_trace_open()
 489 posix_trace_rewind()
 490 posix_trace_set_filter()
 491 posix_trace_shutdown()
 492 posix_trace_timedgetnext_event()
 493 posix_typed_mem_open()
 494 printf()
 495 psiginfo() [Added in POSIX.1-2008]
 496 psignal() [Added in POSIX.1-2008]
 497 pthread_rwlock_rdlock()
 498 pthread_rwlock_timedrdlock()
 499 pthread_rwlock_timedwrlock()
 500 pthread_rwlock_wrlock()
 501 putc()
 502 putc_unlocked()
 503 putchar()
 504 putchar_unlocked()
 505 puts()
 506 pututxline()
 507 putwc()
 508 putwchar()
 509 readdir()
 510 readdir_r()
 511 readlink() [Added in POSIX.1-2008]
 512 readlinkat() [Added in POSIX.1-2008]
 513 remove()
 514 rename()
 515 renameat() [Added in POSIX.1-2008]
 516 rewind()
 517 rewinddir()
 518 scandir() [Added in POSIX.1-2008]
 519 scanf()
 520 seekdir()
 521 semop()
 522 setgrent()
 523 sethostent()
 524 setnetent()
 525 setprotoent()
 526 setpwent()
 527 setservent()
 528 setutxent()
 529 sigpause() [Added in POSIX.1-2008]
 530 stat()
 531 strerror()
 532 strerror_r()
 533 strftime()
 534 symlink()
 535 symlinkat() [Added in POSIX.1-2008]
 536 sync()
 537 syslog()
 538 tmpfile()
 539 tmpnam()
 540 ttyname()
 541 ttyname_r()
 542 tzset()
 543 ungetc()
 544 ungetwc()
 545 unlink()
 546 unlinkat() [Added in POSIX.1-2008]
 547 utime() [Added in POSIX.1-2008]
 548 utimensat() [Added in POSIX.1-2008]
 549 utimes() [Added in POSIX.1-2008]
 550 vdprintf() [Added in POSIX.1-2008]
 551 vfprintf()
 552 vfwprintf()
 553 vprintf()
 554 vwprintf()
 555 wcsftime()
 556 wordexp()
 557 wprintf()
 558 wscanf()
 559 .EE
 560 .in
 561 .PP
 562 An implementation may also mark other functions
 563 not specified in the standard as cancellation points.
 564 In particular, an implementation is likely to mark
 565 any nonstandard function that may block as a cancellation point.
 566 (This includes most functions that can touch files.)
 567 .\" So, scanning "cancellation point" comments in the glibc 2.8 header
 568 .\" files, it looks as though at least the following nonstandard
 569 .\" functions are cancellation points:
 570 .\" endnetgrent
 571 .\" endspent
 572 .\" epoll_pwait
 573 .\" epoll_wait
 574 .\" fcloseall
 575 .\" fdopendir
 576 .\" fflush_unlocked
 577 .\" fgetc_unlocked
 578 .\" fgetgrent
 579 .\" fgetgrent_r
 580 .\" fgetpwent
 581 .\" fgetpwent_r
 582 .\" fgets_unlocked
 583 .\" fgetspent
 584 .\" fgetspent_r
 585 .\" fgetwc_unlocked
 586 .\" fgetws_unlocked
 587 .\" fputc_unlocked
 588 .\" fputs_unlocked
 589 .\" fputwc_unlocked
 590 .\" fputws_unlocked
 591 .\" fread_unlocked
 592 .\" fwrite_unlocked
 593 .\" gai_suspend
 594 .\" getaddrinfo_a
 595 .\" getdate_r
 596 .\" getgrent_r
 597 .\" getgrouplist
 598 .\" gethostbyaddr_r
 599 .\" gethostbyname2
 600 .\" gethostbyname2_r
 601 .\" gethostbyname_r
 602 .\" gethostent_r
 603 .\" getnetbyaddr_r
 604 .\" getnetbyname_r
 605 .\" getnetent_r
 606 .\" getnetgrent
 607 .\" getnetgrent_r
 608 .\" getprotobyname_r
 609 .\" getprotobynumber_r
 610 .\" getprotoent_r
 611 .\" getpw
 612 .\" getpwent_r
 613 .\" getservbyname_r
 614 .\" getservbyport_r
 615 .\" getservent_r
 616 .\" getspent
 617 .\" getspent_r
 618 .\" getspnam
 619 .\" getspnam_r
 620 .\" getutmp
 621 .\" getutmpx
 622 .\" getw
 623 .\" getwc_unlocked
 624 .\" getwchar_unlocked
 625 .\" initgroups
 626 .\" innetgr
 627 .\" mkostemp
 628 .\" mkostemp64
 629 .\" mkstemp64
 630 .\" ppoll
 631 .\" pthread_timedjoin_np
 632 .\" putgrent
 633 .\" putpwent
 634 .\" putspent
 635 .\" putw
 636 .\" putwc_unlocked
 637 .\" putwchar_unlocked
 638 .\" rcmd
 639 .\" rcmd_af
 640 .\" rexec
 641 .\" rexec_af
 642 .\" rresvport
 643 .\" rresvport_af
 644 .\" ruserok
 645 .\" ruserok_af
 646 .\" setnetgrent
 647 .\" setspent
 648 .\" sgetspent
 649 .\" sgetspent_r
 650 .\" updwtmpx
 651 .\" utmpxname
 652 .\" vfscanf
 653 .\" vfwscanf
 654 .\" vscanf
 655 .\" vsyslog
 656 .\" vwscanf
 657 .SS Compiling on Linux
 658 On Linux, programs that use the Pthreads API should be compiled using
 659 .IR "cc \-pthread" .
 660 .SS Linux implementations of POSIX threads
 661 Over time, two threading implementations have been provided by
 662 the GNU C library on Linux:
 663 .TP
 664 .B LinuxThreads
 665 This is the original Pthreads implementation.
 666 Since glibc 2.4, this implementation is no longer supported.
 667 .TP
 668 .BR NPTL " (Native POSIX Threads Library)"
 669 This is the modern Pthreads implementation.
 670 By comparison with LinuxThreads, NPTL provides closer conformance to
 671 the requirements of the POSIX.1 specification and better performance
 672 when creating large numbers of threads.
 673 NPTL is available since glibc 2.3.2,
 674 and requires features that are present in the Linux 2.6 kernel.
 675 .PP
 676 Both of these are so-called 1:1 implementations, meaning that each
 677 thread maps to a kernel scheduling entity.
 678 Both threading implementations employ the Linux
 679 .BR clone (2)
 680 system call.
 681 In NPTL, thread synchronization primitives (mutexes,
 682 thread joining, and so on) are implemented using the Linux
 683 .BR futex (2)
 684 system call.
 685 .SS LinuxThreads
 686 The notable features of this implementation are the following:
 687 .IP \- 3
 688 In addition to the main (initial) thread,
 689 and the threads that the program creates using
 690 .BR pthread_create (3),
 691 the implementation creates a "manager" thread.
 692 This thread handles thread creation and termination.
 693 (Problems can result if this thread is inadvertently killed.)
 694 .IP \- 3
 695 Signals are used internally by the implementation.
 696 On Linux 2.2 and later, the first three real-time signals are used
 697 (see also
 698 .BR signal (7)).
 699 On older Linux kernels,
 700 .B SIGUSR1
 701 and
 702 .B SIGUSR2
 703 are used.
 704 Applications must avoid the use of whichever set of signals is
 705 employed by the implementation.
 706 .IP \- 3
 707 Threads do not share process IDs.
 708 (In effect, LinuxThreads threads are implemented as processes which share
 709 more information than usual, but which do not share a common process ID.)
 710 LinuxThreads threads (including the manager thread)
 711 are visible as separate processes using
 712 .BR ps (1).
 713 .PP
 714 The LinuxThreads implementation deviates from the POSIX.1
 715 specification in a number of ways, including the following:
 716 .IP \- 3
 717 Calls to
 718 .BR getpid (2)
 719 return a different value in each thread.
 720 .IP \- 3
 721 Calls to
 722 .BR getppid (2)
 723 in threads other than the main thread return the process ID of the
 724 manager thread; instead
 725 .BR getppid (2)
 726 in these threads should return the same value as
 727 .BR getppid (2)
 728 in the main thread.
 729 .IP \- 3
 730 When one thread creates a new child process using
 731 .BR fork (2),
 732 any thread should be able to
 733 .BR wait (2)
 734 on the child.
 735 However, the implementation allows only the thread that
 736 created the child to
 737 .BR wait (2)
 738 on it.
 739 .IP \- 3
 740 When a thread calls
 741 .BR execve (2),
 742 all other threads are terminated (as required by POSIX.1).
 743 However, the resulting process has the same PID as the thread that called
 744 .BR execve (2):
 745 it should have the same PID as the main thread.
 746 .IP \- 3
 747 Threads do not share user and group IDs.
 748 This can cause complications with set-user-ID programs and
 749 can cause failures in Pthreads functions if an application
 750 changes its credentials using
 751 .BR seteuid (2)
 752 or similar.
 753 .IP \- 3
 754 Threads do not share a common session ID and process group ID.
 755 .IP \- 3
 756 Threads do not share record locks created using
 757 .BR fcntl (2).
 758 .IP \- 3
 759 The information returned by
 760 .BR times (2)
 761 and
 762 .BR getrusage (2)
 763 is per-thread rather than process-wide.
 764 .IP \- 3
 765 Threads do not share semaphore undo values (see
 766 .BR semop (2)).
 767 .IP \- 3
 768 Threads do not share interval timers.
 769 .IP \- 3
 770 Threads do not share a common nice value.
 771 .IP \- 3
 772 POSIX.1 distinguishes the notions of signals that are directed
 773 to the process as a whole and signals that are directed to individual
 774 threads.
 775 According to POSIX.1, a process-directed signal (sent using
 776 .BR kill (2),
 777 for example) should be handled by a single,
 778 arbitrarily selected thread within the process.
 779 LinuxThreads does not support the notion of process-directed signals:
 780 signals may be sent only to specific threads.
 781 .IP \- 3
 782 Threads have distinct alternate signal stack settings.
 783 However, a new thread's alternate signal stack settings
 784 are copied from the thread that created it, so that
 785 the threads initially share an alternate signal stack.
 786 (A new thread should start with no alternate signal stack defined.
 787 If two threads handle signals on their shared alternate signal
 788 stack at the same time, unpredictable program failures are
 789 likely to occur.)
 790 .SS NPTL
 791 With NPTL, all of the threads in a process are placed
 792 in the same thread group;
 793 all members of a thread group share the same PID.
 794 NPTL does not employ a manager thread.
 795 .PP
 796 NPTL makes internal use of the first two real-time signals;
 797 these signals cannot be used in applications.
 798 See
 799 .BR nptl (7)
 800 for further details.
 801 .PP
 802 NPTL still has at least one nonconformance with POSIX.1:
 803 .IP \- 3
 804 Threads do not share a common nice value.
 805 .\" FIXME . bug report filed for NPTL nice nonconformance
 806 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258
 807 .\" Sep 08: there is a patch by Denys Vlasenko to address this
 808 .\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension"
 809 .\" Monitor this to see if it makes it into mainline.
 810 .PP
 811 Some NPTL nonconformances occur only with older kernels:
 812 .IP \- 3
 813 The information returned by
 814 .BR times (2)
 815 and
 816 .BR getrusage (2)
 817 is per-thread rather than process-wide (fixed in kernel 2.6.9).
 818 .IP \- 3
 819 Threads do not share resource limits (fixed in kernel 2.6.10).
 820 .IP \- 3
 821 Threads do not share interval timers (fixed in kernel 2.6.12).
 822 .IP \- 3
 823 Only the main thread is permitted to start a new session using
 824 .BR setsid (2)
 825 (fixed in kernel 2.6.16).
 826 .IP \- 3
 827 Only the main thread is permitted to make the process into a
 828 process group leader using
 829 .BR setpgid (2)
 830 (fixed in kernel 2.6.16).
 831 .IP \- 3
 832 Threads have distinct alternate signal stack settings.
 833 However, a new thread's alternate signal stack settings
 834 are copied from the thread that created it, so that
 835 the threads initially share an alternate signal stack
 836 (fixed in kernel 2.6.16).
 837 .PP
 838 Note the following further points about the NPTL implementation:
 839 .IP \- 3
 840 If the stack size soft resource limit (see the description of
 841 .B RLIMIT_STACK
 842 in
 843 .BR setrlimit (2))
 844 is set to a value other than
 845 .IR unlimited ,
 846 then this value defines the default stack size for new threads.
 847 To be effective, this limit must be set before the program
 848 is executed, perhaps using the
 849 .I ulimit -s
 850 shell built-in command
 851 .RI ( "limit stacksize"
 852 in the C shell).
 853 .SS Determining the threading implementation
 854 Since glibc 2.3.2, the
 855 .BR getconf (1)
 856 command can be used to determine
 857 the system's threading implementation, for example:
 858 .PP
 859 .in +4n
 860 .EX
 861 bash$ getconf GNU_LIBPTHREAD_VERSION
 862 NPTL 2.3.4
 863 .EE
 864 .in
 865 .PP
 866 With older glibc versions, a command such as the following should
 867 be sufficient to determine the default threading implementation:
 868 .PP
 869 .in +4n
 870 .EX
 871 bash$ $( ldd /bin/ls | grep libc.so | awk \(aq{print $3}\(aq ) | \e
 872                 egrep \-i \(aqthreads|nptl\(aq
 873         Native POSIX Threads Library by Ulrich Drepper et al
 874 .EE
 875 .in
 876 .SS Selecting the threading implementation: LD_ASSUME_KERNEL
 877 On systems with a glibc that supports both LinuxThreads and NPTL
 878 (i.e., glibc 2.3.\fIx\fP), the
 879 .B LD_ASSUME_KERNEL
 880 environment variable can be used to override
 881 the dynamic linker's default choice of threading implementation.
 882 This variable tells the dynamic linker to assume that it is
 883 running on top of a particular kernel version.
 884 By specifying a kernel version that does not
 885 provide the support required by NPTL, we can force the use
 886 of LinuxThreads.
 887 (The most likely reason for doing this is to run a
 888 (broken) application that depends on some nonconformant behavior
 889 in LinuxThreads.)
 890 For example:
 891 .PP
 892 .in +4n
 893 .EX
 894 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e
 895                 awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|nptl\(aq
 896         linuxthreads-0.10 by Xavier Leroy
 897 .EE
 898 .in
 899 .SH SEE ALSO
 900 .ad l
 901 .nh
 902 .BR clone (2),
 903 .BR fork (2),
 904 .BR futex (2),
 905 .BR gettid (2),
 906 .BR proc (5),
 907 .BR attributes (7),
 908 .BR futex (7),
 909 .BR nptl (7),
 910 .BR sigevent (7),
 911 .BR signal (7)
 912 .PP
 913 Various Pthreads manual pages, for example:
 914 .BR pthread_atfork (3),
 915 .BR pthread_attr_init (3),
 916 .BR pthread_cancel (3),
 917 .BR pthread_cleanup_push (3),
 918 .BR pthread_cond_signal (3),
 919 .BR pthread_cond_wait (3),
 920 .BR pthread_create (3),
 921 .BR pthread_detach (3),
 922 .BR pthread_equal (3),
 923 .BR pthread_exit (3),
 924 .BR pthread_key_create (3),
 925 .BR pthread_kill (3),
 926 .BR pthread_mutex_lock (3),
 927 .BR pthread_mutex_unlock (3),
 928 .BR pthread_mutexattr_destroy (3),
 929 .BR pthread_mutexattr_init (3),
 930 .BR pthread_once (3),
 931 .BR pthread_spin_init (3),
 932 .BR pthread_spin_lock (3),
 933 .BR pthread_rwlockattr_setkind_np (3),
 934 .BR pthread_setcancelstate (3),
 935 .BR pthread_setcanceltype (3),
 936 .BR pthread_setspecific (3),
 937 .BR pthread_sigmask (3),
 938 .BR pthread_sigqueue (3),
 939 and
 940 .BR pthread_testcancel (3)