2 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .TH PTHREADS 7 2008-11-18 "Linux" "Linux Programmer's Manual"
26 pthreads \- POSIX threads
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).
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):
42 process group ID and session ID
55 file mode creation mask
67 .RB ( timer_create (2))
70 .RB ( setpriority (2))
75 measurements of the consumption of CPU time
80 As well as the stack, POSIX.1 specifies that various other
81 attributes are distinct for each thread, including:
88 .RB ( pthread_sigmask (3))
94 alternate signal stack
95 .RB ( sigaltstack (2))
97 real-time scheduling policy and priority
98 .RB ( sched_setscheduler (2)
100 .BR sched_setparam (2))
102 The following Linux-specific features are also per-thread:
105 .BR capabilities (7))
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
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
117 Each of the threads in a process has a unique thread identifier
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.
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:
145 ctermid() if passed a non-NULL argument
159 ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
164 fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
166 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
174 gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
175 gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
222 strsignal() [Added in POSIX.1-2008]
224 system() [Added in POSIX.1-2008]
225 tmpnam() if passed a non-NULL argument
228 wcrtomb() if its final argument is NULL
229 wcsrtombs() if its final argument is NULL
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.
242 The following functions are required to be cancellation points by
243 POSIX.1-2001 and/or POSIX.1-2008:
246 .\" Document the list of all functions that are cancellation points in glibc
270 openat() [Added in POSIX.1-2008]
275 pthread_cond_timedwait()
293 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
301 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
310 The following functions may be cancellation points according to
311 POSIX.1-2001 and/or POSIX.1-2008:
321 chmod() [Added in POSIX.1-2008]
322 chown() [Added in POSIX.1-2008]
336 dprintf() [Added in POSIX.1-2008]
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]
350 fcntl() (for any value of cmd argument)
372 fstatat() [Added in POSIX.1-2008]
376 futimens() [Added in POSIX.1-2008]
387 getdelim() [Added in POSIX.1-2008]
393 gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]
394 gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]
398 getline() [Added in POSIX.1-2008]
405 getopt() (if opterr is nonzero)
423 getwd() [SUSv3 only (function removed in POSIX.1-2008)]
429 linkat() [Added in POSIX.1-2008]
430 lio_listio() [Added in POSIX.1-2008]
433 lockf() [Added in POSIX.1-2008]
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]
461 posix_trace_create_withlog()
462 posix_trace_eventtypelist_getnext_id()
463 posix_trace_eventtypelist_rewind()
465 posix_trace_get_attr()
466 posix_trace_get_filter()
467 posix_trace_get_status()
468 posix_trace_getnext_event()
471 posix_trace_set_filter()
472 posix_trace_shutdown()
473 posix_trace_timedgetnext_event()
474 posix_typed_mem_open()
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()
492 readlink() [Added in POSIX.1-2008]
493 readlinkat() [Added in POSIX.1-2008]
496 renameat() [Added in POSIX.1-2008]
499 scandir() [Added in POSIX.1-2008]
510 sigpause() [Added in POSIX.1-2008]
516 symlinkat() [Added in POSIX.1-2008]
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]
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:
590 .\" getprotobynumber_r
605 .\" getwchar_unlocked
612 .\" pthread_timedjoin_np
618 .\" putwchar_unlocked
638 .SS "Compiling on Linux"
639 On Linux, programs that use the Pthreads API should be compiled using
641 .SS "Linux Implementations of POSIX Threads"
642 Over time, two threading implementations have been provided by
643 the GNU C library on Linux:
646 This is the original Pthreads implementation.
647 Since glibc 2.4, this implementation is no longer supported.
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.
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
662 In NPTL, thread synchronization primitives (mutexes,
663 thread joining, etc.) are implemented using the Linux
667 The notable features of this implementation are the following:
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.)
676 Signals are used internally by the implementation.
677 On Linux 2.2 and later, the first three real-time signals are used
680 On older Linux kernels,
685 Applications must avoid the use of whichever set of signals is
686 employed by the implementation.
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
695 The LinuxThreads implementation deviates from the POSIX.1
696 specification in a number of ways, including the following:
700 return a different value in each thread.
704 in threads other than the main thread return the process ID of the
705 manager thread; instead
707 in these threads should return the same value as
711 When one thread creates a new child process using
713 any thread should be able to
716 However, the implementation only allows the thread that
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
726 it should have the same PID as the main thread.
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
735 Threads do not share a common session ID and process group ID.
737 Threads do not share record locks created using
740 The information returned by
744 is per-thread rather than process-wide.
746 Threads do not share semaphore undo values (see
749 Threads do not share interval timers.
751 Threads do not share a common nice value.
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
756 According to POSIX.1, a process-directed signal (sent using
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.
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
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
779 these signals cannot be used in applications.
781 NPTL still has at least one nonconformance with POSIX.1:
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.
790 Some NPTL nonconformances only occur with older kernels:
792 The information returned by
796 is per-thread rather than process-wide (fixed in kernel 2.6.9).
798 Threads do not share resource limits (fixed in kernel 2.6.10).
800 Threads do not share interval timers (fixed in kernel 2.6.12).
802 Only the main thread is permitted to start a new session using
804 (fixed in kernel 2.6.16).
806 Only the main thread is permitted to make the process into a
807 process group leader using
809 (fixed in kernel 2.6.16).
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).
817 Note the following further points about the NPTL implementation:
819 If the stack size soft resource limit (see the description of
823 is set to a value other than
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
829 shell built-in command
830 .RI ( "limit stacksize"
832 .SS "Determining the Threading Implementation"
833 Since glibc 2.3.2, the
835 command can be used to determine
836 the system's threading implementation, for example:
840 bash$ getconf GNU_LIBPTHREAD_VERSION
845 With older glibc versions, a command such as the following should
846 be sufficient to determine the default threading implementation:
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
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
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
866 (The most likely reason for doing this is to run a
867 (broken) application that depends on some nonconformant behavior
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
886 and various Pthreads manual pages, for example:
887 .BR pthread_attr_init (3),
888 .BR pthread_atfork (3),
889 .BR pthread_cancel (3),
890 .BR pthread_cleanup_push (3),
891 .BR pthread_cond_signal (3),
892 .BR pthread_cond_wait (3),
893 .BR pthread_create (3),
894 .BR pthread_detach (3),
895 .BR pthread_equal (3),
896 .BR pthread_exit (3),
897 .BR pthread_key_create (3),
898 .BR pthread_kill (3),
899 .BR pthread_mutex_lock (3),
900 .BR pthread_mutex_unlock (3),
901 .BR pthread_once (3),
902 .BR pthread_setcancelstate (3),
903 .BR pthread_setcanceltype (3),
904 .BR pthread_setspecific (3),
905 .BR pthread_sigmask (3),
907 .BR pthread_testcancel (3)