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