'\" t
.\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
-.TH PTHREADS 7 2008-11-18 "Linux" "Linux Programmer's Manual"
+.TH PTHREADS 7 2014-05-21 "Linux" "Linux Programmer's Manual"
.SH NAME
pthreads \- POSIX threads
.SH DESCRIPTION
.RB ( sigaltstack (2))
.IP \- 3
real-time scheduling policy and priority
-.RB ( sched_setscheduler (2)
-and
-.BR sched_setparam (2))
+.RB ( sched (7))
.PP
The following Linux-specific features are also per-thread:
.IP \- 3
.IP \- 3
CPU affinity
.RB ( sched_setaffinity (2))
-.SS "Pthreads function return values"
+.SS Pthreads function return values
Most pthreads functions return 0 on success, and an error number of failure.
Note that the pthreads functions do not set
.IR errno .
.BR pthread_create (3),
and a thread can obtain its own thread identifier using
.BR pthread_self (3).
-Thread IDs are only guaranteed to be unique within a process.
+Thread IDs are guaranteed to be unique only within a process.
A thread ID may be reused after a terminated thread has been joined,
or a detached thread has terminated.
In all pthreads functions that accept a thread ID as an argument,
that ID by definition refers to a thread in
the same process as the caller.
-.SS "Thread-safe functions"
+.SS Thread-safe functions
A thread-safe function is one that can be safely
(i.e., it will deliver the same results regardless of whether it is)
called from multiple threads at the same time.
wctomb()
.fi
.in
-.SS Cancellation Points
+.SS Async-cancel-safe functions
+An async-cancel-safe function is one that can be safely called
+in an application where asynchronous cancelability is enabled (see
+.BR pthread_setcancelstate (3)).
+
+Only the following functions are required to be async-cancel-safe by
+POSIX.1-2001 and POSIX.1-2008:
+.in +4n
+.nf
+
+pthread_cancel()
+pthread_setcancelstate()
+pthread_setcanceltype()
+.fi
+.in
+.SS Cancellation points
POSIX.1 specifies that certain functions must,
and certain other functions may, be cancellation points.
If a thread is cancelable, its cancelability type is deferred,
.\" vscanf
.\" vsyslog
.\" vwscanf
-.SS "Compiling on Linux"
+.SS Compiling on Linux
On Linux, programs that use the Pthreads API should be compiled using
.IR "cc \-pthread" .
-.SS "Linux Implementations of POSIX Threads"
+.SS Linux implementations of POSIX threads
Over time, two threading implementations have been provided by
the GNU C library on Linux:
.TP
.BR clone (2)
system call.
In NPTL, thread synchronization primitives (mutexes,
-thread joining, etc.) are implemented using the Linux
+thread joining, and so on) are implemented using the Linux
.BR futex (2)
system call.
.SS LinuxThreads
any thread should be able to
.BR wait (2)
on the child.
-However, the implementation only allows the thread that
+However, the implementation allows only the thread that
created the child to
.BR wait (2)
on it.
for example) should be handled by a single,
arbitrarily selected thread within the process.
LinuxThreads does not support the notion of process-directed signals:
-signals may only be sent to specific threads.
+signals may be sent only to specific threads.
.IP \- 3
Threads have distinct alternate signal stack settings.
However, a new thread's alternate signal stack settings
.\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension"
.\" Monitor this to see if it makes it into mainline.
.PP
-Some NPTL nonconformances only occur with older kernels:
+Some NPTL nonconformances occur only with older kernels:
.IP \- 3
The information returned by
.BR times (2)
shell built-in command
.RI ( "limit stacksize"
in the C shell).
-.SS "Determining the Threading Implementation"
+.SS Determining the threading implementation
Since glibc 2.3.2, the
.BR getconf (1)
command can be used to determine
Native POSIX Threads Library by Ulrich Drepper et al
.in
.fi
-.SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL"
+.SS Selecting the threading implementation: LD_ASSUME_KERNEL
On systems with a glibc that supports both LinuxThreads and NPTL
(i.e., glibc 2.3.\fIx\fP), the
.B LD_ASSUME_KERNEL
.in +4n
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\
- awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|ntpl\(aq
+ awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|nptl\(aq
linuxthreads-0.10 by Xavier Leroy
.in
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
+.ad l
+.nh
.BR clone (2),
.BR futex (2),
.BR gettid (2),
.BR futex (7),
.BR sigevent (7),
.BR signal (7),
-.br
-and various Pthreads manual pages, for example:
+
+Various Pthreads manual pages, for example:
.BR pthread_attr_init (3),
.BR pthread_atfork (3),
.BR pthread_cancel (3),
.BR pthread_setcanceltype (3),
.BR pthread_setspecific (3),
.BR pthread_sigmask (3),
+.BR pthread_sigqueue (3),
and
.BR pthread_testcancel (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.