2 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH PTHREADS 7 2010-11-14 "Linux" "Linux Programmer's Manual"
28 pthreads \- POSIX threads
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).
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):
44 process group ID and session ID
57 file mode creation mask
69 .RB ( timer_create (2))
72 .RB ( setpriority (2))
77 measurements of the consumption of CPU time
82 As well as the stack, POSIX.1 specifies that various other
83 attributes are distinct for each thread, including:
90 .RB ( pthread_sigmask (3))
96 alternate signal stack
97 .RB ( sigaltstack (2))
99 real-time scheduling policy and priority
100 .RB ( sched_setscheduler (2)
102 .BR sched_setparam (2))
104 The following Linux-specific features are also per-thread:
107 .BR capabilities (7))
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
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
119 Each of the threads in a process has a unique thread identifier
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.
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:
147 ctermid() if passed a non-NULL argument
161 ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
166 fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
168 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
176 gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
177 gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
224 strsignal() [Added in POSIX.1-2008]
226 system() [Added in POSIX.1-2008]
227 tmpnam() if passed a non-NULL argument
230 wcrtomb() if its final argument is NULL
231 wcsrtombs() if its final argument is NULL
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)).
241 Only the following functions are required to be async-cancel-safe by
242 POSIX.1-2001 and POSIX.1-2008:
247 pthread_setcancelstate()
248 pthread_setcanceltype()
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.
259 The following functions are required to be cancellation points by
260 POSIX.1-2001 and/or POSIX.1-2008:
263 .\" Document the list of all functions that are cancellation points in glibc
287 openat() [Added in POSIX.1-2008]
292 pthread_cond_timedwait()
310 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
318 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
327 The following functions may be cancellation points according to
328 POSIX.1-2001 and/or POSIX.1-2008:
338 chmod() [Added in POSIX.1-2008]
339 chown() [Added in POSIX.1-2008]
353 dprintf() [Added in POSIX.1-2008]
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]
367 fcntl() (for any value of cmd argument)
389 fstatat() [Added in POSIX.1-2008]
393 futimens() [Added in POSIX.1-2008]
404 getdelim() [Added in POSIX.1-2008]
410 gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]
411 gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]
415 getline() [Added in POSIX.1-2008]
422 getopt() (if opterr is nonzero)
440 getwd() [SUSv3 only (function removed in POSIX.1-2008)]
446 linkat() [Added in POSIX.1-2008]
447 lio_listio() [Added in POSIX.1-2008]
450 lockf() [Added in POSIX.1-2008]
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]
478 posix_trace_create_withlog()
479 posix_trace_eventtypelist_getnext_id()
480 posix_trace_eventtypelist_rewind()
482 posix_trace_get_attr()
483 posix_trace_get_filter()
484 posix_trace_get_status()
485 posix_trace_getnext_event()
488 posix_trace_set_filter()
489 posix_trace_shutdown()
490 posix_trace_timedgetnext_event()
491 posix_typed_mem_open()
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()
509 readlink() [Added in POSIX.1-2008]
510 readlinkat() [Added in POSIX.1-2008]
513 renameat() [Added in POSIX.1-2008]
516 scandir() [Added in POSIX.1-2008]
527 sigpause() [Added in POSIX.1-2008]
533 symlinkat() [Added in POSIX.1-2008]
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]
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:
607 .\" getprotobynumber_r
622 .\" getwchar_unlocked
629 .\" pthread_timedjoin_np
635 .\" putwchar_unlocked
655 .SS Compiling on Linux
656 On Linux, programs that use the Pthreads API should be compiled using
658 .SS Linux implementations of POSIX threads
659 Over time, two threading implementations have been provided by
660 the GNU C library on Linux:
663 This is the original Pthreads implementation.
664 Since glibc 2.4, this implementation is no longer supported.
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.
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
679 In NPTL, thread synchronization primitives (mutexes,
680 thread joining, and so on) are implemented using the Linux
684 The notable features of this implementation are the following:
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.)
693 Signals are used internally by the implementation.
694 On Linux 2.2 and later, the first three real-time signals are used
697 On older Linux kernels,
702 Applications must avoid the use of whichever set of signals is
703 employed by the implementation.
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
712 The LinuxThreads implementation deviates from the POSIX.1
713 specification in a number of ways, including the following:
717 return a different value in each thread.
721 in threads other than the main thread return the process ID of the
722 manager thread; instead
724 in these threads should return the same value as
728 When one thread creates a new child process using
730 any thread should be able to
733 However, the implementation only allows the thread that
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
743 it should have the same PID as the main thread.
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
752 Threads do not share a common session ID and process group ID.
754 Threads do not share record locks created using
757 The information returned by
761 is per-thread rather than process-wide.
763 Threads do not share semaphore undo values (see
766 Threads do not share interval timers.
768 Threads do not share a common nice value.
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
773 According to POSIX.1, a process-directed signal (sent using
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.
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
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
796 these signals cannot be used in applications.
798 NPTL still has at least one nonconformance with POSIX.1:
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.
807 Some NPTL nonconformances occur only with older kernels:
809 The information returned by
813 is per-thread rather than process-wide (fixed in kernel 2.6.9).
815 Threads do not share resource limits (fixed in kernel 2.6.10).
817 Threads do not share interval timers (fixed in kernel 2.6.12).
819 Only the main thread is permitted to start a new session using
821 (fixed in kernel 2.6.16).
823 Only the main thread is permitted to make the process into a
824 process group leader using
826 (fixed in kernel 2.6.16).
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).
834 Note the following further points about the NPTL implementation:
836 If the stack size soft resource limit (see the description of
840 is set to a value other than
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
846 shell built-in command
847 .RI ( "limit stacksize"
849 .SS Determining the threading implementation
850 Since glibc 2.3.2, the
852 command can be used to determine
853 the system's threading implementation, for example:
857 bash$ getconf GNU_LIBPTHREAD_VERSION
862 With older glibc versions, a command such as the following should
863 be sufficient to determine the default threading implementation:
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
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
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
883 (The most likely reason for doing this is to run a
884 (broken) application that depends on some nonconformant behavior
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
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),
928 .BR pthread_testcancel (3)
930 This page is part of release 3.64 of the Linux
933 A description of the project,
934 and information about reporting bugs,
936 \%http://www.kernel.org/doc/man\-pages/.