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