pthreads (7) - Linux Manuals
pthreads: POSIX threads
NAME
pthreads - POSIX threads
DESCRIPTION
POSIX.1 specifies a set of interfaces (functions, header files) for threaded programming commonly known as POSIX threads, or Pthreads. A single process can contain multiple threads, 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):
- -
- process ID
- -
- parent process ID
- -
- process group ID and session ID
- -
- controlling terminal
- -
- user and group IDs
- -
- open file descriptors
- -
- record locks (see fcntl(2))
- -
- signal dispositions
- -
- file mode creation mask (umask(2))
- -
- current directory (chdir(2)) and root directory (chroot(2))
- -
- interval timers (setitimer(2)) and POSIX timers (timer_create(2))
- -
- nice value (setpriority(2))
- -
- resource limits (setrlimit(2))
- -
- measurements of the consumption of CPU time (times(2)) and resources (getrusage(2))
As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including:
- -
- thread ID (the pthread_t data type)
- -
- signal mask (pthread_sigmask(3))
- -
- the errno variable
- -
- alternate signal stack (sigaltstack(2))
- -
- real-time scheduling policy and priority (sched(7))
The following Linux-specific features are also per-thread:
- -
- capabilities (see capabilities(7))
- -
- CPU affinity (sched_setaffinity(2))
Pthreads function return values
Most pthreads functions return 0 on success, and an error number on failure. The error numbers that can be returned have the same meaning as the error numbers returned in errno by conventional system calls and C library functions. Note that the pthreads functions do not set errno. For each of the pthreads functions that can return an error, POSIX.1-2001 specifies that the function can never fail with the error EINTR.Thread IDs
Each of the threads in a process has a unique thread identifier (stored in the type pthread_t). This identifier is returned to the caller of pthread_create(3), and a thread can obtain its own thread identifier using pthread_self(3).Thread IDs are guaranteed to be unique only within a process. (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.)
The system may reuse a thread ID after a terminated thread has been joined, or a detached thread has terminated. POSIX says: "If an application attempts to use a thread ID whose lifetime has ended, the behavior is undefined."
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.POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the standard shall be thread-safe, except for the following functions:
asctime()
basename()
catgets()
crypt()
ctermid() if passed a non-NULL argument
ctime()
dbm_clearerr()
dbm_close()
dbm_delete()
dbm_error()
dbm_fetch()
dbm_firstkey()
dbm_nextkey()
dbm_open()
dbm_store()
dirname()
dlerror()
drand48()
ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
encrypt()
endgrent()
endpwent()
endutxent()
fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
ftw()
gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
getc_unlocked()
getchar_unlocked()
getdate()
getenv()
getgrent()
getgrgid()
getgrnam()
gethostbyaddr() [POSIX.1-2001 only (function removed in
Only the following functions are required to be async-cancel-safe by
POSIX.1-2001 and POSIX.1-2008:
pthread_cancel()
pthread_setcancelstate()
pthread_setcanceltype()
The following functions are required to be cancellation points by
POSIX.1-2001 and/or POSIX.1-2008:
accept()
aio_suspend()
clock_nanosleep()
close()
connect()
creat()
fcntl() F_SETLKW
fdatasync()
fsync()
getmsg()
getpmsg()
lockf() F_LOCK
mq_receive()
mq_send()
mq_timedreceive()
mq_timedsend()
msgrcv()
msgsnd()
msync()
nanosleep()
open()
openat() [Added in POSIX.1-2008]
pause()
poll()
pread()
pselect()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_join()
pthread_testcancel()
putmsg()
putpmsg()
pwrite()
read()
readv()
recv()
recvfrom()
recvmsg()
select()
sem_timedwait()
sem_wait()
send()
sendmsg()
sendto()
sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
sigsuspend()
sigtimedwait()
sigwait()
sigwaitinfo()
sleep()
system()
tcdrain()
usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
wait()
waitid()
waitpid()
write()
writev()
The following functions may be cancellation points according to
POSIX.1-2001 and/or POSIX.1-2008:
access()
asctime()
asctime_r()
catclose()
catgets()
catopen()
chmod() [Added in POSIX.1-2008]
chown() [Added in POSIX.1-2008]
closedir()
closelog()
ctermid()
ctime()
ctime_r()
dbm_close()
dbm_delete()
dbm_fetch()
dbm_nextkey()
dbm_open()
dbm_store()
dlclose()
dlopen()
dprintf() [Added in POSIX.1-2008]
endgrent()
endhostent()
endnetent()
endprotoent()
endpwent()
endservent()
endutxent()
faccessat() [Added in POSIX.1-2008]
fchmod() [Added in POSIX.1-2008]
fchmodat() [Added in POSIX.1-2008]
fchown() [Added in POSIX.1-2008]
fchownat() [Added in POSIX.1-2008]
fclose()
fcntl() (for any value of cmd argument)
fflush()
fgetc()
fgetpos()
fgets()
fgetwc()
fgetws()
fmtmsg()
fopen()
fpathconf()
fprintf()
fputc()
fputs()
fputwc()
fputws()
fread()
freopen()
fscanf()
fseek()
fseeko()
fsetpos()
fstat()
fstatat() [Added in POSIX.1-2008]
ftell()
ftello()
ftw()
futimens() [Added in POSIX.1-2008]
fwprintf()
fwrite()
fwscanf()
getaddrinfo()
getc()
getc_unlocked()
getchar()
getchar_unlocked()
getcwd()
getdate()
getdelim() [Added in POSIX.1-2008]
getgrent()
getgrgid()
getgrgid_r()
getgrnam()
getgrnam_r()
gethostbyaddr() [POSIX.1-2001 only (function removed in
An implementation may also mark other functions
not specified in the standard as cancellation points.
In particular, an implementation is likely to mark
any nonstandard function that may block as a cancellation point.
(This includes most functions that can touch files.)
It should be noted that even if an application is not using
asynchronous cancellation, that calling a function from the above list
from an asynchronous signal handler may cause the equivalent of
asynchronous cancellation.
The underlying user code may not expect
asynchronous cancellation and the state of the user data may become
inconsistent.
Therefore signals should be used with caution when
entering a region of deferred cancellation.
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
clone(2)
system call.
In NPTL, thread synchronization primitives (mutexes,
thread joining, and so on) are implemented using the Linux
futex(2)
system call.
The LinuxThreads implementation deviates from the POSIX.1
specification in a number of ways, including the following:
NPTL makes internal use of the first two real-time signals;
these signals cannot be used in applications.
See
nptl(7)
for further details.
NPTL still has at least one nonconformance with POSIX.1:
Some NPTL nonconformances occur only with older kernels:
Note the following further points about the NPTL implementation:
bash$ getconf GNU_LIBPTHREAD_VERSION
NPTL 2.3.4
With older glibc versions, a command such as the following should
be sufficient to determine the default threading implementation:
bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
Various Pthreads manual pages, for example:
pthread_atfork(3),
pthread_attr_init(3),
pthread_cancel(3),
pthread_cleanup_push(3),
pthread_cond_signal(3),
pthread_cond_wait(3),
pthread_create(3),
pthread_detach(3),
pthread_equal(3),
pthread_exit(3),
pthread_key_create(3),
pthread_kill(3),
pthread_mutex_lock(3),
pthread_mutex_unlock(3),
pthread_mutexattr_destroy(3),
pthread_mutexattr_init(3),
pthread_once(3),
pthread_spin_init(3),
pthread_spin_lock(3),
pthread_rwlockattr_setkind_np(3),
pthread_setcancelstate(3),
pthread_setcanceltype(3),
pthread_setspecific(3),
pthread_sigmask(3),
pthread_sigqueue(3),
and
pthread_testcancel(3)
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
pthread_setcancelstate(3)).
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,
and a cancellation request is pending for the thread,
then the thread is canceled when it calls a function
that is a cancellation point.
Compiling on Linux
On Linux, programs that use the Pthreads API should be compiled using
cc -pthread.
Linux implementations of POSIX threads
Over time, two threading implementations have been provided by
the GNU C library on Linux:
LinuxThreads
The notable features of this implementation are the following:
NPTL
With NPTL, all of the threads in a process are placed
in the same thread group;
all members of a thread group share the same PID.
NPTL does not employ a manager thread.
Determining the threading implementation
Since glibc 2.3.2, the
getconf(1)
command can be used to determine
the system's threading implementation, for example:
Selecting the threading implementation: LD_ASSUME_KERNEL
On systems with a glibc that supports both LinuxThreads and NPTL
(i.e., glibc 2.3.x), the
LD_ASSUME_KERNEL
environment variable can be used to override
the dynamic linker's default choice of threading implementation.
This variable tells the dynamic linker to assume that it is
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 nonconformant behavior
in LinuxThreads.)
For example:
COLOPHON
This page is part of release 5.10 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
https://www.kernel.org/doc/man-pages/.
SEE ALSO
clone(2),
fork(2),
futex(2),
gettid(2),
proc(5),
attributes(7),
futex(7),
nptl(7),
sigevent(7),
signal(7)