1 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" %%%LICENSE_START(VERBATIM)
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.
25 .TH PTHREADS 7 2021-03-22 "Linux" "Linux Programmer's Manual"
27 pthreads \- POSIX threads
29 POSIX.1 specifies a set of interfaces (functions, header files) for
30 threaded programming commonly known as POSIX threads, or Pthreads.
31 A single process can contain multiple threads,
32 all of which are executing the same program.
33 These threads share the same global memory (data and heap segments),
34 but each thread has its own stack (automatic variables).
36 POSIX.1 also requires that threads share a range of other attributes
37 (i.e., these attributes are process-wide rather than per-thread):
43 process group ID and session ID
56 file mode creation mask
68 .RB ( timer_create (2))
71 .RB ( setpriority (2))
76 measurements of the consumption of CPU time
81 As well as the stack, POSIX.1 specifies that various other
82 attributes are distinct for each thread, including:
89 .RB ( pthread_sigmask (3))
95 alternate signal stack
96 .RB ( sigaltstack (2))
98 real-time scheduling policy and priority
101 The following Linux-specific features are also per-thread:
104 .BR capabilities (7))
107 .RB ( sched_setaffinity (2))
108 .SS Pthreads function return values
109 Most pthreads functions return 0 on success, and an error number on failure.
110 The error numbers that can be returned have the same meaning as
111 the error numbers returned in
113 by conventional system calls and C library functions.
114 Note that the pthreads functions do not set
116 For each of the pthreads functions that can return an error,
117 POSIX.1-2001 specifies that the function can never fail with the error
120 Each of the threads in a process has a unique thread identifier
123 This identifier is returned to the caller of
124 .BR pthread_create (3),
125 and a thread can obtain its own thread identifier using
126 .BR pthread_self (3).
128 Thread IDs are guaranteed to be unique only within a process.
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.)
133 The system may reuse a thread ID after a terminated thread has been joined,
134 or a detached thread has terminated.
135 POSIX says: "If an application attempts to use a thread ID whose
136 lifetime has ended, the behavior is undefined."
137 .SS Thread-safe functions
138 A thread-safe function is one that can be safely
139 (i.e., it will deliver the same results regardless of whether it is)
140 called from multiple threads at the same time.
142 POSIX.1-2001 and POSIX.1-2008 require that all functions specified
143 in the standard shall be thread-safe,
144 except for the following functions:
152 ctermid() if passed a non-NULL argument
166 ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
171 fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
173 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
181 gethostbyaddr() [POSIX.1-2001 only (function removed in
183 gethostbyname() [POSIX.1-2001 only (function removed in
231 strsignal() [Added in POSIX.1-2008]
233 system() [Added in POSIX.1-2008]
234 tmpnam() if passed a non-NULL argument
237 wcrtomb() if its final argument is NULL
238 wcsrtombs() if its final argument is NULL
243 .SS Async-cancel-safe functions
244 An async-cancel-safe function is one that can be safely called
245 in an application where asynchronous cancelability is enabled (see
246 .BR pthread_setcancelstate (3)).
248 Only the following functions are required to be async-cancel-safe by
249 POSIX.1-2001 and POSIX.1-2008:
254 pthread_setcancelstate()
255 pthread_setcanceltype()
258 .SS Cancellation points
259 POSIX.1 specifies that certain functions must,
260 and certain other functions may, be cancellation points.
261 If a thread is cancelable, its cancelability type is deferred,
262 and a cancellation request is pending for the thread,
263 then the thread is canceled when it calls a function
264 that is a cancellation point.
266 The following functions are required to be cancellation points by
267 POSIX.1-2001 and/or POSIX.1-2008:
270 .\" Document the list of all functions that are cancellation points in glibc
294 openat() [Added in POSIX.1-2008]
299 pthread_cond_timedwait()
317 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
325 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
334 The following functions may be cancellation points according to
335 POSIX.1-2001 and/or POSIX.1-2008:
345 chmod() [Added in POSIX.1-2008]
346 chown() [Added in POSIX.1-2008]
360 dprintf() [Added in POSIX.1-2008]
368 faccessat() [Added in POSIX.1-2008]
369 fchmod() [Added in POSIX.1-2008]
370 fchmodat() [Added in POSIX.1-2008]
371 fchown() [Added in POSIX.1-2008]
372 fchownat() [Added in POSIX.1-2008]
374 fcntl() (for any value of cmd argument)
396 fstatat() [Added in POSIX.1-2008]
400 futimens() [Added in POSIX.1-2008]
411 getdelim() [Added in POSIX.1-2008]
417 gethostbyaddr() [POSIX.1-2001 only (function removed in
419 gethostbyname() [POSIX.1-2001 only (function removed in
424 getline() [Added in POSIX.1-2008]
431 getopt() (if opterr is nonzero)
449 getwd() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
455 linkat() [Added in POSIX.1-2008]
456 lio_listio() [Added in POSIX.1-2008]
459 lockf() [Added in POSIX.1-2008]
462 mkdir() [Added in POSIX.1-2008]
463 mkdirat() [Added in POSIX.1-2008]
464 mkdtemp() [Added in POSIX.1-2008]
465 mkfifo() [Added in POSIX.1-2008]
466 mkfifoat() [Added in POSIX.1-2008]
467 mknod() [Added in POSIX.1-2008]
468 mknodat() [Added in POSIX.1-2008]
487 posix_trace_create_withlog()
488 posix_trace_eventtypelist_getnext_id()
489 posix_trace_eventtypelist_rewind()
491 posix_trace_get_attr()
492 posix_trace_get_filter()
493 posix_trace_get_status()
494 posix_trace_getnext_event()
497 posix_trace_set_filter()
498 posix_trace_shutdown()
499 posix_trace_timedgetnext_event()
500 posix_typed_mem_open()
502 psiginfo() [Added in POSIX.1-2008]
503 psignal() [Added in POSIX.1-2008]
504 pthread_rwlock_rdlock()
505 pthread_rwlock_timedrdlock()
506 pthread_rwlock_timedwrlock()
507 pthread_rwlock_wrlock()
518 readlink() [Added in POSIX.1-2008]
519 readlinkat() [Added in POSIX.1-2008]
522 renameat() [Added in POSIX.1-2008]
525 scandir() [Added in POSIX.1-2008]
536 sigpause() [Added in POSIX.1-2008]
542 symlinkat() [Added in POSIX.1-2008]
553 unlinkat() [Added in POSIX.1-2008]
554 utime() [Added in POSIX.1-2008]
555 utimensat() [Added in POSIX.1-2008]
556 utimes() [Added in POSIX.1-2008]
557 vdprintf() [Added in POSIX.1-2008]
569 An implementation may also mark other functions
570 not specified in the standard as cancellation points.
571 In particular, an implementation is likely to mark
572 any nonstandard function that may block as a cancellation point.
573 (This includes most functions that can touch files.)
575 It should be noted that even if an application is not using
576 asynchronous cancellation, that calling a function from the above list
577 from an asynchronous signal handler may cause the equivalent of
578 asynchronous cancellation.
579 The underlying user code may not expect
580 asynchronous cancellation and the state of the user data may become
582 Therefore signals should be used with caution when
583 entering a region of deferred cancellation.
584 .\" So, scanning "cancellation point" comments in the glibc 2.8 header
585 .\" files, it looks as though at least the following nonstandard
586 .\" functions are cancellation points:
626 .\" getprotobynumber_r
641 .\" getwchar_unlocked
648 .\" pthread_timedjoin_np
654 .\" putwchar_unlocked
674 .SS Compiling on Linux
675 On Linux, programs that use the Pthreads API should be compiled using
677 .SS Linux implementations of POSIX threads
678 Over time, two threading implementations have been provided by
679 the GNU C library on Linux:
682 This is the original Pthreads implementation.
683 Since glibc 2.4, this implementation is no longer supported.
685 .BR NPTL " (Native POSIX Threads Library)"
686 This is the modern Pthreads implementation.
687 By comparison with LinuxThreads, NPTL provides closer conformance to
688 the requirements of the POSIX.1 specification and better performance
689 when creating large numbers of threads.
690 NPTL is available since glibc 2.3.2,
691 and requires features that are present in the Linux 2.6 kernel.
693 Both of these are so-called 1:1 implementations, meaning that each
694 thread maps to a kernel scheduling entity.
695 Both threading implementations employ the Linux
698 In NPTL, thread synchronization primitives (mutexes,
699 thread joining, and so on) are implemented using the Linux
703 The notable features of this implementation are the following:
705 In addition to the main (initial) thread,
706 and the threads that the program creates using
707 .BR pthread_create (3),
708 the implementation creates a "manager" thread.
709 This thread handles thread creation and termination.
710 (Problems can result if this thread is inadvertently killed.)
712 Signals are used internally by the implementation.
713 On Linux 2.2 and later, the first three real-time signals are used
716 On older Linux kernels,
721 Applications must avoid the use of whichever set of signals is
722 employed by the implementation.
724 Threads do not share process IDs.
725 (In effect, LinuxThreads threads are implemented as processes which share
726 more information than usual, but which do not share a common process ID.)
727 LinuxThreads threads (including the manager thread)
728 are visible as separate processes using
731 The LinuxThreads implementation deviates from the POSIX.1
732 specification in a number of ways, including the following:
736 return a different value in each thread.
740 in threads other than the main thread return the process ID of the
741 manager thread; instead
743 in these threads should return the same value as
747 When one thread creates a new child process using
749 any thread should be able to
752 However, the implementation allows only the thread that
759 all other threads are terminated (as required by POSIX.1).
760 However, the resulting process has the same PID as the thread that called
762 it should have the same PID as the main thread.
764 Threads do not share user and group IDs.
765 This can cause complications with set-user-ID programs and
766 can cause failures in Pthreads functions if an application
767 changes its credentials using
771 Threads do not share a common session ID and process group ID.
773 Threads do not share record locks created using
776 The information returned by
780 is per-thread rather than process-wide.
782 Threads do not share semaphore undo values (see
785 Threads do not share interval timers.
787 Threads do not share a common nice value.
789 POSIX.1 distinguishes the notions of signals that are directed
790 to the process as a whole and signals that are directed to individual
792 According to POSIX.1, a process-directed signal (sent using
794 for example) should be handled by a single,
795 arbitrarily selected thread within the process.
796 LinuxThreads does not support the notion of process-directed signals:
797 signals may be sent only to specific threads.
799 Threads have distinct alternate signal stack settings.
800 However, a new thread's alternate signal stack settings
801 are copied from the thread that created it, so that
802 the threads initially share an alternate signal stack.
803 (A new thread should start with no alternate signal stack defined.
804 If two threads handle signals on their shared alternate signal
805 stack at the same time, unpredictable program failures are
808 With NPTL, all of the threads in a process are placed
809 in the same thread group;
810 all members of a thread group share the same PID.
811 NPTL does not employ a manager thread.
813 NPTL makes internal use of the first two real-time signals;
814 these signals cannot be used in applications.
819 NPTL still has at least one nonconformance with POSIX.1:
821 Threads do not share a common nice value.
822 .\" FIXME . bug report filed for NPTL nice nonconformance
823 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258
824 .\" Sep 08: there is a patch by Denys Vlasenko to address this
825 .\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension"
826 .\" Monitor this to see if it makes it into mainline.
828 Some NPTL nonconformances occur only with older kernels:
830 The information returned by
834 is per-thread rather than process-wide (fixed in kernel 2.6.9).
836 Threads do not share resource limits (fixed in kernel 2.6.10).
838 Threads do not share interval timers (fixed in kernel 2.6.12).
840 Only the main thread is permitted to start a new session using
842 (fixed in kernel 2.6.16).
844 Only the main thread is permitted to make the process into a
845 process group leader using
847 (fixed in kernel 2.6.16).
849 Threads have distinct alternate signal stack settings.
850 However, a new thread's alternate signal stack settings
851 are copied from the thread that created it, so that
852 the threads initially share an alternate signal stack
853 (fixed in kernel 2.6.16).
855 Note the following further points about the NPTL implementation:
857 If the stack size soft resource limit (see the description of
861 is set to a value other than
863 then this value defines the default stack size for new threads.
864 To be effective, this limit must be set before the program
865 is executed, perhaps using the
867 shell built-in command
868 .RI ( "limit stacksize"
870 .SS Determining the threading implementation
871 Since glibc 2.3.2, the
873 command can be used to determine
874 the system's threading implementation, for example:
878 bash$ getconf GNU_LIBPTHREAD_VERSION
883 With older glibc versions, a command such as the following should
884 be sufficient to determine the default threading implementation:
888 bash$ $( ldd /bin/ls | grep libc.so | awk \(aq{print $3}\(aq ) | \e
889 egrep \-i \(aqthreads|nptl\(aq
890 Native POSIX Threads Library by Ulrich Drepper et al
893 .SS Selecting the threading implementation: LD_ASSUME_KERNEL
894 On systems with a glibc that supports both LinuxThreads and NPTL
895 (i.e., glibc 2.3.\fIx\fP), the
897 environment variable can be used to override
898 the dynamic linker's default choice of threading implementation.
899 This variable tells the dynamic linker to assume that it is
900 running on top of a particular kernel version.
901 By specifying a kernel version that does not
902 provide the support required by NPTL, we can force the use
904 (The most likely reason for doing this is to run a
905 (broken) application that depends on some nonconformant behavior
911 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e
912 awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|nptl\(aq
913 linuxthreads\-0.10 by Xavier Leroy
930 Various Pthreads manual pages, for example:
931 .BR pthread_atfork (3),
932 .BR pthread_attr_init (3),
933 .BR pthread_cancel (3),
934 .BR pthread_cleanup_push (3),
935 .BR pthread_cond_signal (3),
936 .BR pthread_cond_wait (3),
937 .BR pthread_create (3),
938 .BR pthread_detach (3),
939 .BR pthread_equal (3),
940 .BR pthread_exit (3),
941 .BR pthread_key_create (3),
942 .BR pthread_kill (3),
943 .BR pthread_mutex_lock (3),
944 .BR pthread_mutex_unlock (3),
945 .BR pthread_mutexattr_destroy (3),
946 .BR pthread_mutexattr_init (3),
947 .BR pthread_once (3),
948 .BR pthread_spin_init (3),
949 .BR pthread_spin_lock (3),
950 .BR pthread_rwlockattr_setkind_np (3),
951 .BR pthread_setcancelstate (3),
952 .BR pthread_setcanceltype (3),
953 .BR pthread_setspecific (3),
954 .BR pthread_sigmask (3),
955 .BR pthread_sigqueue (3),
957 .BR pthread_testcancel (3)