2005-06-07 12:35:32 +00:00
|
|
|
'\" t
|
|
|
|
.\" Copyright (c) 2005 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2005-06-08 13:27:21 +00:00
|
|
|
.\"
|
2005-06-07 12:35:32 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein.
|
2005-06-08 13:27:21 +00:00
|
|
|
.\"
|
2005-06-07 12:35:32 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.TH PTHREADS 7 2005-06-07 "Linux 2.6.12" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
pthreads \- POSIX threads
|
|
|
|
.SH DESCRIPTION
|
2005-06-08 13:27:21 +00:00
|
|
|
POSIX.1 specifies a set of interfaces (functions, header files) for
|
2005-06-07 12:35:32 +00:00
|
|
|
threaded programming commonly known as POSIX threads, or Pthreads.
|
2005-06-08 13:27:21 +00:00
|
|
|
A single process can contain multiple threads,
|
2005-06-07 12:35:32 +00:00
|
|
|
all of which are executing the same program.
|
|
|
|
These threads share the same global memory (data and heap segments),
|
|
|
|
but each thread has its own stack (automatic variables).
|
|
|
|
|
|
|
|
POSIX.1 also requires that threads share a range of other attributes
|
|
|
|
(i.e., these attributes are process-wide rather than per-thread):
|
|
|
|
.IP \- 3
|
|
|
|
process ID
|
|
|
|
.IP \- 3
|
|
|
|
parent process ID
|
|
|
|
.IP \- 3
|
|
|
|
process group ID and session ID
|
|
|
|
.IP \- 3
|
|
|
|
controlling terminal
|
|
|
|
.IP \- 3
|
|
|
|
user and group IDs
|
|
|
|
.IP \- 3
|
|
|
|
open file descriptors
|
|
|
|
.IP \- 3
|
|
|
|
record locks (see
|
|
|
|
.BR fcntl (2))
|
|
|
|
.IP \- 3
|
|
|
|
signal dispositions
|
|
|
|
.IP \- 3
|
|
|
|
file mode creation mask
|
|
|
|
.RB ( umask (2))
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
current directory
|
2005-06-07 12:35:32 +00:00
|
|
|
.RB ( chdir (2))
|
|
|
|
and
|
|
|
|
root directory
|
|
|
|
.RB ( chroot (2))
|
|
|
|
.IP \- 3
|
|
|
|
interval timers
|
|
|
|
.RB ( setitimer (2))
|
|
|
|
and POSIX timers
|
|
|
|
.RB ( timer_create ())
|
|
|
|
.IP \- 3
|
|
|
|
nice value
|
|
|
|
.RB ( setpriority (2))
|
|
|
|
.IP \- 3
|
|
|
|
resource limits
|
|
|
|
.RB ( setrlimit (2))
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
measurements of the consumption of CPU time
|
2005-06-07 12:35:32 +00:00
|
|
|
.RB ( times (2))
|
2005-06-08 13:27:21 +00:00
|
|
|
and resources
|
2005-06-07 12:35:32 +00:00
|
|
|
.RB ( getrusage (2))
|
|
|
|
.PP
|
|
|
|
As well as the stack, POSIX.1 specifies that various other
|
|
|
|
attributes are distinct for each thread, including:
|
|
|
|
.IP \- 3
|
|
|
|
thread ID (the
|
|
|
|
.I pthread_t
|
|
|
|
data type)
|
|
|
|
.IP \- 3
|
|
|
|
signal mask
|
2005-10-19 13:21:05 +00:00
|
|
|
.RB ( pthread_sigmask ())
|
2005-06-07 12:35:32 +00:00
|
|
|
.IP \- 3
|
|
|
|
the
|
|
|
|
.I errno
|
|
|
|
variable
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
alternate signal stack
|
2005-06-07 12:35:32 +00:00
|
|
|
.RB ( sigaltstack (2))
|
|
|
|
.IP \- 3
|
|
|
|
real-time scheduling policy and priority
|
|
|
|
.RB ( sched_setscheduler (2)
|
|
|
|
and
|
|
|
|
.BR sched_setparam (2))
|
|
|
|
.PP
|
|
|
|
The following Linux-specific features are also per-thread:
|
|
|
|
.IP \- 3
|
|
|
|
capabilities (see
|
|
|
|
.BR capabilities (7))
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
CPU affinity
|
2005-06-07 12:35:32 +00:00
|
|
|
.RB ( sched_setaffinity (2))
|
|
|
|
.SS "Compiling on Linux"
|
|
|
|
On Linux, programs that use the Pthreads API should be compiled using
|
2005-07-06 07:41:37 +00:00
|
|
|
.IR "cc \-pthread" .
|
2005-06-07 12:35:32 +00:00
|
|
|
.SS "Linux Implementations of POSIX Threads"
|
|
|
|
Over time, two threading implementations have been provided by
|
|
|
|
the GNU C library on Linux:
|
|
|
|
.IP \- 3
|
2005-07-19 15:36:19 +00:00
|
|
|
.B LinuxThreads
|
2005-06-07 12:35:32 +00:00
|
|
|
This is the original (now obsolete) Pthreads implementation.
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
.B NPTL
|
2005-06-07 12:35:32 +00:00
|
|
|
(Native POSIX Threads Library)
|
|
|
|
This is the modern Pthreads implementation.
|
|
|
|
By comparison with LinuxThreads, NPTL provides closer conformance to
|
2005-06-08 13:27:21 +00:00
|
|
|
the requirements of the POSIX.1 specification and better performance
|
2005-06-07 12:35:32 +00:00
|
|
|
when creating large numbers of threads.
|
2005-06-13 09:51:27 +00:00
|
|
|
NPTL requires features that are present in the Linux 2.6 kernel.
|
2005-06-07 12:35:32 +00:00
|
|
|
.PP
|
|
|
|
Both of these are so-called 1:1 implementations, meaning that each
|
|
|
|
thread maps to a kernel scheduling entity.
|
|
|
|
|
|
|
|
Both threading implementations employ the Linux
|
|
|
|
.BR clone (2)
|
|
|
|
system call.
|
2005-06-08 13:27:21 +00:00
|
|
|
In NPTL, thread synchronisation primitives (mutexes,
|
2005-06-07 12:35:32 +00:00
|
|
|
thread joining, etc.) are implemented using the Linux
|
|
|
|
.BR futex (2)
|
|
|
|
system call.
|
|
|
|
.PP
|
|
|
|
Modern GNU C libraries provide both LinuxThreads and NPTL, with the
|
|
|
|
latter being the default (if supported by the underlying kernel).
|
|
|
|
.SS LinuxThreads
|
|
|
|
The notable features of this implementation are the following:
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
In addition to the main (initial) thread,
|
|
|
|
and the threads that the program creates using
|
2005-06-07 12:35:32 +00:00
|
|
|
.BR pthread_create (),
|
|
|
|
the implementation creates a "manager" thread.
|
|
|
|
This thread handles thread creation and termination.
|
|
|
|
(Problems can result if this thread is inadvertently killed.)
|
|
|
|
.IP \- 3
|
|
|
|
Signals are used internally by the implementation.
|
|
|
|
On Linux 2.2 and later, the first three real-time signals are used.
|
|
|
|
On older Linux kernels, SIGUSR1 and SIGUSR2 are used.
|
2005-06-08 13:27:21 +00:00
|
|
|
Applications must avoid the use of whichever set of signals is
|
2005-06-07 12:35:32 +00:00
|
|
|
employed by the implementation.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share process IDs.
|
|
|
|
(In effect, LinuxThreads threads are implemented as processes which share
|
|
|
|
more information than usual, but which do not share a common process ID.)
|
|
|
|
LinuxThreads threads (including the manager thread)
|
|
|
|
are visible as separate processes using
|
|
|
|
.BR ps (1).
|
|
|
|
.PP
|
|
|
|
The LinuxThreads implementation deviates from the POSIX.1
|
|
|
|
specification in a number of ways, including the following:
|
|
|
|
.IP \- 3
|
|
|
|
Calls to
|
|
|
|
.BR getpid (2)
|
|
|
|
return a different value in each thread.
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
Calls to
|
2005-06-07 12:35:32 +00:00
|
|
|
.BR getppid (2)
|
|
|
|
in threads other than the main thread return the process ID of the
|
|
|
|
manager thread; instead
|
|
|
|
.BR getppid (2)
|
|
|
|
in these threads should return the same value as
|
|
|
|
.BR getppid (2)
|
|
|
|
in the main thread.
|
|
|
|
.IP \- 3
|
|
|
|
When one thread creates a new child process using
|
|
|
|
.BR fork (2),
|
|
|
|
any thread should be able to
|
|
|
|
.BR wait (2)
|
|
|
|
on the child.
|
2005-06-08 13:27:21 +00:00
|
|
|
However, the implementation only allows the thread that
|
2005-06-07 12:35:32 +00:00
|
|
|
created the child to
|
|
|
|
.BR wait (2)
|
|
|
|
on it.
|
|
|
|
.IP \- 3
|
|
|
|
When a thread calls
|
|
|
|
.BR execve (2),
|
|
|
|
all other threads are terminated (as required by POSIX.1).
|
|
|
|
However, the resulting process has the same PID as the thread that called
|
|
|
|
.BR execve (2):
|
|
|
|
it should have the same PID as the main thread.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share user and group IDs.
|
2005-07-18 14:25:42 +00:00
|
|
|
This can cause complications with set-user-ID programs and
|
2005-06-07 12:35:32 +00:00
|
|
|
can cause failures in Pthreads functions if an application
|
|
|
|
changes its credentials using
|
|
|
|
.BR seteuid (2)
|
|
|
|
or similar.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share a common session ID and process group ID.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share record locks created using
|
|
|
|
.BR fcntl (2).
|
|
|
|
.IP \- 3
|
|
|
|
The information returned by
|
|
|
|
.BR times (2)
|
|
|
|
and
|
|
|
|
.BR getrusage (2)
|
|
|
|
is per-thread rather than process-wide.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share semaphore undo values (see
|
|
|
|
.BR semop (2)).
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share interval timers.
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share a common nice value.
|
|
|
|
.IP \- 3
|
|
|
|
POSIX.1 distinguishes the notions of signals that are directed
|
|
|
|
to the process as a whole and signals are directed to individual
|
|
|
|
threads.
|
|
|
|
According to POSIX.1, a process-directed signal (sent using
|
|
|
|
.BR kill (2),
|
|
|
|
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.
|
|
|
|
.IP \- 3
|
2005-06-08 13:27:21 +00:00
|
|
|
Threads have distinct alternate signal stack settings.
|
|
|
|
However, a new thread's alternate signal stack settings
|
2005-07-05 13:53:03 +00:00
|
|
|
are copied from the thread that created it, so that
|
2005-06-08 13:27:21 +00:00
|
|
|
the threads initially share an alternate signal stack.
|
|
|
|
(A new thread should start with no alternate signal stack defined.
|
|
|
|
If two threads handle signals on their shared alternate signal
|
|
|
|
stack at the same time, unpredictable program failures are
|
|
|
|
likely to occur.)
|
2005-06-07 12:35:32 +00:00
|
|
|
.SS NPTL
|
|
|
|
With NPTL, all of the threads in a process are placed
|
|
|
|
in the same thread group;
|
|
|
|
all members of a thread groups share the same PID.
|
2005-06-08 13:27:21 +00:00
|
|
|
NPTL does not employ a manager thread.
|
|
|
|
NPTL makes internal use of the first two real-time signals;
|
|
|
|
these signals cannot be used in applications.
|
|
|
|
|
2005-06-07 12:35:32 +00:00
|
|
|
NPTL still has a few non-conformances with POSIX.1:
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share a common nice value.
|
2006-03-22 20:18:10 +00:00
|
|
|
.\" FIXME . bug report filed for NPTL nice non-conformance
|
|
|
|
.\" http://bugzilla.kernel.org/show_bug.cgi?id=6258
|
2005-06-07 12:35:32 +00:00
|
|
|
.PP
|
|
|
|
Some NPTL non-conformances only occur with older kernels:
|
|
|
|
.IP \- 3
|
|
|
|
The information returned by
|
|
|
|
.BR times (2)
|
|
|
|
and
|
|
|
|
.BR getrusage (2)
|
|
|
|
is per-thread rather than process-wide (fixed in kernel 2.6.9).
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share resource limits (fixed in kernel 2.6.10).
|
|
|
|
.IP \- 3
|
|
|
|
Threads do not share interval timers (fixed in kernel 2.6.12).
|
2006-03-05 09:00:21 +00:00
|
|
|
.IP \- 3
|
|
|
|
Only the main thread is permitted to start a new session using
|
|
|
|
.BR setsid (2)
|
|
|
|
(fixed in kernel 2.6.16).
|
|
|
|
.IP \- 3
|
|
|
|
Only the main thread is permitted to make the process into a
|
|
|
|
process group leader using
|
|
|
|
.BR setpgid (2)
|
|
|
|
(fixed in kernel 2.6.16).
|
2006-03-21 04:13:05 +00:00
|
|
|
.IP \- 3
|
|
|
|
Threads have distinct alternate signal stack settings.
|
|
|
|
However, a new thread's alternate signal stack settings
|
|
|
|
are copied from the thread that created it, so that
|
|
|
|
the threads initially share an alternate signal stack
|
|
|
|
(fixed in kernel 2.6.16).
|
2005-06-07 12:35:32 +00:00
|
|
|
.SS "Determining the Threading Implementation"
|
2005-06-08 13:27:21 +00:00
|
|
|
Since glibc 2.3.2, the
|
2005-06-07 12:35:32 +00:00
|
|
|
.BR getconf (1)
|
|
|
|
command can be used to determine
|
|
|
|
the system's default threading implementation, for example:
|
|
|
|
.nf
|
|
|
|
.in +4
|
|
|
|
|
|
|
|
bash$ getconf GNU_LIBPTHREAD_VERSION
|
|
|
|
NPTL 2.3.4
|
|
|
|
.in -4
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
With older glibc versions, a command such as the following should
|
|
|
|
be sufficient to determine the default threading implementation:
|
|
|
|
.nf
|
|
|
|
.in +4
|
|
|
|
|
|
|
|
bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \\
|
2005-07-06 12:57:38 +00:00
|
|
|
egrep \-i 'threads|ntpl'
|
2005-06-07 12:35:32 +00:00
|
|
|
Native POSIX Threads Library by Ulrich Drepper et al
|
|
|
|
.in -4
|
|
|
|
.fi
|
|
|
|
.SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL"
|
|
|
|
On systems with a glibc that supports both LinuxThreads and NPTL,
|
|
|
|
the LD_ASSUME_KERNEL environment variable can be used to override
|
|
|
|
the dynamic linker's default choice of threading implementation.
|
2005-06-08 13:27:21 +00:00
|
|
|
This variable tells the dynamic linker to assume that it is
|
2005-06-07 12:35:32 +00:00
|
|
|
running on top of a particular kernel version.
|
|
|
|
By specifying a kernel version that does not
|
|
|
|
provide the support required by NPTL, we can force the use
|
|
|
|
of LinuxThreads.
|
|
|
|
(The most likely reason for doing this is to run a
|
|
|
|
(broken) application that depends on some non-conformant behavior
|
|
|
|
in LinuxThreads.)
|
|
|
|
For example:
|
|
|
|
.nf
|
|
|
|
.in +4
|
|
|
|
|
|
|
|
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\
|
2005-07-06 12:57:38 +00:00
|
|
|
awk '{print $3}' ) | egrep \-i 'threads|ntpl'
|
2005-06-07 12:35:32 +00:00
|
|
|
linuxthreads-0.10 by Xavier Leroy
|
|
|
|
.in -4
|
|
|
|
.fi
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR clone (2),
|
|
|
|
.BR futex (2),
|
|
|
|
.BR gettid (2),
|
|
|
|
.BR futex (4),
|
|
|
|
and various Pthreads manual pages, for example:
|
|
|
|
.BR pthread_atfork (3),
|
|
|
|
.BR pthread_cleanup_push (3),
|
|
|
|
.BR pthread_cond_signal (3),
|
|
|
|
.BR pthread_cond_wait (3),
|
|
|
|
.BR pthread_create (3),
|
|
|
|
.BR pthread_detach (3),
|
|
|
|
.BR pthread_equal (3),
|
|
|
|
.BR pthread_exit (3),
|
|
|
|
.BR pthread_key_create (3),
|
|
|
|
.BR pthread_kill (3),
|
|
|
|
.BR pthread_mutex_lock (3),
|
|
|
|
.BR pthread_mutex_unlock (3),
|
|
|
|
.BR pthread_once (3),
|
|
|
|
.BR pthread_setcancelstate (3),
|
|
|
|
.BR pthread_setcanceltype (3),
|
|
|
|
.BR pthread_setspecific (3),
|
|
|
|
.BR pthread_sigmask (3),
|
|
|
|
and
|
|
|
|
.BR pthread_testcancel (3).
|