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