pthreads(7)

1PTHREADS(7)                Linux Programmer's Manual               PTHREADS(7)
2
3
4

NAME

6       pthreads - POSIX threads
7

DESCRIPTION

9       POSIX.1  specifies  a  set  of interfaces (functions, header files) for
10       threaded programming commonly known as POSIX threads, or  Pthreads.   A
11       single process can contain multiple threads, all of which are executing
12       the same program.  These threads share the same global memory (data and
13       heap  segments),  but  each  thread  has its own stack (automatic vari‐
14       ables).
15
16       POSIX.1 also requires that threads share a range  of  other  attributes
17       (i.e., these attributes are process-wide rather than per-thread):
18
19       -  process ID
20
21       -  parent process ID
22
23       -  process group ID and session ID
24
25       -  controlling terminal
26
27       -  user and group IDs
28
29       -  open file descriptors
30
31       -  record locks (see fcntl(2))
32
33       -  signal dispositions
34
35       -  file mode creation mask (umask(2))
36
37       -  current directory (chdir(2)) and root directory (chroot(2))
38
39       -  interval timers (setitimer(2)) and POSIX timers (timer_create())
40
41       -  nice value (setpriority(2))
42
43       -  resource limits (setrlimit(2))
44
45       -  measurements of the consumption of CPU time (times(2)) and resources
46          (getrusage(2))
47
48       As well as the stack, POSIX.1 specifies that various  other  attributes
49       are distinct for each thread, including:
50
51       -  thread ID (the pthread_t data type)
52
53       -  signal mask (pthread_sigmask())
54
55       -  the errno variable
56
57       -  alternate signal stack (sigaltstack(2))
58
59       -  real-time  scheduling policy and priority (sched_setscheduler(2) and
60          sched_setparam(2))
61
62       The following Linux-specific features are also per-thread:
63
64       -  capabilities (see capabilities(7))
65
66       -  CPU affinity (sched_setaffinity(2))
67
68   Compiling on Linux
69       On Linux, programs that use the Pthreads API should be  compiled  using
70       cc -pthread.
71
72   Linux Implementations of POSIX Threads
73       Over  time, two threading implementations have been provided by the GNU
74       C library on Linux:
75
76       -  LinuxThreads This is the original (now obsolete) Pthreads  implemen‐
77          tation.
78
79       -  NPTL  (Native  POSIX  Threads  Library)  This is the modern Pthreads
80          implementation.  By  comparison  with  LinuxThreads,  NPTL  provides
81          closer  conformance to the requirements of the POSIX.1 specification
82          and better performance when creating large numbers of threads.  NPTL
83          requires features that are present in the Linux 2.6 kernel.
84
85       Both  of  these  are  so-called  1:1 implementations, meaning that each
86       thread maps to a kernel scheduling entity.
87
88       Both threading implementations employ the Linux clone(2)  system  call.
89       In  NPTL,  thread  synchronisation primitives (mutexes, thread joining,
90       etc.) are implemented using the Linux futex(2) system call.
91
92       Modern GNU C libraries provide both LinuxThreads  and  NPTL,  with  the
93       latter being the default (if supported by the underlying kernel).
94
95   LinuxThreads
96       The notable features of this implementation are the following:
97
98       -  In  addition  to the main (initial) thread, and the threads that the
99          program creates using pthread_create(), the implementation creates a
100          "manager"  thread.  This thread handles thread creation and termina‐
101          tion.  (Problems can result if this thread is inadvertently killed.)
102
103       -  Signals are used internally by the implementation.  On Linux 2.2 and
104          later,  the  first three real-time signals are used.  On older Linux
105          kernels, SIGUSR1 and SIGUSR2 are used.  Applications must avoid  the
106          use of whichever set of signals is employed by the implementation.
107
108       -  Threads  do not share process IDs.  (In effect, LinuxThreads threads
109          are implemented as  processes  which  share  more  information  than
110          usual,  but  which  do not share a common process ID.)  LinuxThreads
111          threads (including the manager thread) are visible as separate  pro‐
112          cesses using ps(1).
113
114       The LinuxThreads implementation deviates from the POSIX.1 specification
115       in a number of ways, including the following:
116
117       -  Calls to getpid(2) return a different value in each thread.
118
119       -  Calls to getppid(2) in threads other than the main thread return the
120          process  ID  of  the  manager  thread;  instead  getppid(2) in these
121          threads should return the same  value  as  getppid(2)  in  the  main
122          thread.
123
124       -  When  one  thread  creates  a  new  child process using fork(2), any
125          thread should be able to wait(2) on the child.  However, the  imple‐
126          mentation  only  allows the thread that created the child to wait(2)
127          on it.
128
129       -  When a thread calls execve(2), all other threads are terminated  (as
130          required  by  POSIX.1).  However, the resulting process has the same
131          PID as the thread that called execve(2): it should have the same PID
132          as the main thread.
133
134       -  Threads  do  not share user and group IDs.  This can cause complica‐
135          tions with set-user-ID programs and can cause failures  in  Pthreads
136          functions if an application changes its credentials using seteuid(2)
137          or similar.
138
139       -  Threads do not share a common session ID and process group ID.
140
141       -  Threads do not share record locks created using fcntl(2).
142
143       -  The information returned by times(2) and getrusage(2) is  per-thread
144          rather than process-wide.
145
146       -  Threads do not share semaphore undo values (see semop(2)).
147
148       -  Threads do not share interval timers.
149
150       -  Threads do not share a common nice value.
151
152       -  POSIX.1  distinguishes  the  notions of signals that are directed to
153          the process as a  whole  and  signals  are  directed  to  individual
154          threads.   According  to  POSIX.1,  a  process-directed signal (sent
155          using kill(2), for example) should be handled by a single, arbitrar‐
156          ily  selected thread within the process.  LinuxThreads does not sup‐
157          port the notion of process-directed signals:  signals  may  only  be
158          sent to specific threads.
159
160       -  Threads  have  distinct alternate signal stack settings.  However, a
161          new thread's alternate signal stack settings  are  copied  from  the
162          thread  that  created  it,  so  that  the threads initially share an
163          alternate signal stack.  (A new thread should start with  no  alter‐
164          nate  signal  stack defined.  If two threads handle signals on their
165          shared alternate signal stack at the same time,  unpredictable  pro‐
166          gram failures are likely to occur.)
167
168   NPTL
169       With  NPTL,  all  of  the  threads  in a process are placed in the same
170       thread group; all members of a thread groups share the same PID.   NPTL
171       does not employ a manager thread.  NPTL makes internal use of the first
172       two real-time signals; these signals cannot be used in applications.
173
174       NPTL still has a few non-conformances with POSIX.1:
175
176       -  Threads do not share a common nice value.
177
178       Some NPTL non-conformances only occur with older kernels:
179
180       -  The information returned by times(2) and getrusage(2) is  per-thread
181          rather than process-wide (fixed in kernel 2.6.9).
182
183       -  Threads do not share resource limits (fixed in kernel 2.6.10).
184
185       -  Threads do not share interval timers (fixed in kernel 2.6.12).
186
187       -  Only  the main thread is permitted to start a new session using set‐
188          sid(2) (fixed in kernel 2.6.16).
189
190       -  Only the main thread is permitted to make the process into a process
191          group leader using setpgid(2) (fixed in kernel 2.6.16).
192
193       -  Threads  have  distinct alternate signal stack settings.  However, a
194          new thread's alternate signal stack settings  are  copied  from  the
195          thread  that  created  it,  so  that  the threads initially share an
196          alternate signal stack (fixed in kernel 2.6.16).
197
198       Note the following further points about the NPTL implementation:
199
200       -  If the stack size  soft  resource  limit  (see  the  description  of
201          RLIMIT_STACK  in  setrlimit(2))  is set to a value other than unlim‐
202          ited, then this  value  defines  the  default  stack  size  for  new
203          threads.  To be effective, this limit must be set before the program
204          is executed, perhaps using the  ulimit  -s  shell  built-in  command
205          (limit stacksize in the C shell).
206
207   Determining the Threading Implementation
208       Since  glibc 2.3.2, the getconf(1) command can be used to determine the
209       system's default threading implementation, for example:
210
211           bash$ getconf GNU_LIBPTHREAD_VERSION
212           NPTL 2.3.4
213
214       With older glibc versions, a command such as the  following  should  be
215       sufficient to determine the default threading implementation:
216
217           bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
218                           egrep -i 'threads|ntpl'
219                   Native POSIX Threads Library by Ulrich Drepper et al
220
221   Selecting the Threading Implementation: LD_ASSUME_KERNEL
222       On  systems  with a glibc that supports both LinuxThreads and NPTL, the
223       LD_ASSUME_KERNEL environment variable  can  be  used  to  override  the
224       dynamic  linker's  default  choice  of  threading implementation.  This
225       variable tells the dynamic linker to assume that it is running  on  top
226       of  a  particular  kernel version.  By specifying a kernel version that
227       does not provide the support required by NPTL, we can force the use  of
228       LinuxThreads.  (The most likely reason for doing this is to run a (bro‐
229       ken) application that depends on some non-conformant behavior in Linux‐
230       Threads.)  For example:
231
232           bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
233                           awk '{print $3}' ) | egrep -i 'threads|ntpl'
234                   linuxthreads-0.10 by Xavier Leroy
235

NAME

DESCRIPTION

SEE ALSO