]>
Commit | Line | Data |
---|---|---|
3616b7c0 MK |
1 | '\" t |
2 | .\" Copyright (c) 2005 by Michael Kerrisk <mtk-manpages@gmx.net> | |
3 | .\" | |
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. | |
7 | .\" | |
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. | |
23a6e651 | 12 | .\" |
3616b7c0 MK |
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. | |
23a6e651 | 17 | .\" |
3616b7c0 MK |
18 | .\" Formatted or processed versions of this manual, if unaccompanied by |
19 | .\" the source, must acknowledge the copyright and authors of this work. | |
20 | .\" | |
d9343c5c | 21 | .TH PTHREADS 7 2005-06-07 "Linux" "Linux Programmer's Manual" |
3616b7c0 MK |
22 | .SH NAME |
23 | pthreads \- POSIX threads | |
24 | .SH DESCRIPTION | |
23a6e651 | 25 | POSIX.1 specifies a set of interfaces (functions, header files) for |
3616b7c0 | 26 | threaded programming commonly known as POSIX threads, or Pthreads. |
23a6e651 | 27 | A single process can contain multiple threads, |
3616b7c0 MK |
28 | all of which are executing the same program. |
29 | These threads share the same global memory (data and heap segments), | |
30 | but each thread has its own stack (automatic variables). | |
31 | ||
32 | POSIX.1 also requires that threads share a range of other attributes | |
33 | (i.e., these attributes are process-wide rather than per-thread): | |
34 | .IP \- 3 | |
35 | process ID | |
36 | .IP \- 3 | |
37 | parent process ID | |
38 | .IP \- 3 | |
39 | process group ID and session ID | |
40 | .IP \- 3 | |
41 | controlling terminal | |
42 | .IP \- 3 | |
43 | user and group IDs | |
44 | .IP \- 3 | |
45 | open file descriptors | |
46 | .IP \- 3 | |
47 | record locks (see | |
48 | .BR fcntl (2)) | |
49 | .IP \- 3 | |
50 | signal dispositions | |
51 | .IP \- 3 | |
52 | file mode creation mask | |
53 | .RB ( umask (2)) | |
54 | .IP \- 3 | |
23a6e651 | 55 | current directory |
3616b7c0 MK |
56 | .RB ( chdir (2)) |
57 | and | |
58 | root directory | |
59 | .RB ( chroot (2)) | |
60 | .IP \- 3 | |
61 | interval timers | |
62 | .RB ( setitimer (2)) | |
63 | and POSIX timers | |
63f6a20a | 64 | .RB ( timer_create (3)) |
3616b7c0 MK |
65 | .IP \- 3 |
66 | nice value | |
67 | .RB ( setpriority (2)) | |
68 | .IP \- 3 | |
69 | resource limits | |
70 | .RB ( setrlimit (2)) | |
71 | .IP \- 3 | |
23a6e651 | 72 | measurements of the consumption of CPU time |
3616b7c0 | 73 | .RB ( times (2)) |
23a6e651 | 74 | and resources |
3616b7c0 MK |
75 | .RB ( getrusage (2)) |
76 | .PP | |
77 | As well as the stack, POSIX.1 specifies that various other | |
78 | attributes are distinct for each thread, including: | |
79 | .IP \- 3 | |
80 | thread ID (the | |
81 | .I pthread_t | |
82 | data type) | |
83 | .IP \- 3 | |
84 | signal mask | |
63f6a20a | 85 | .RB ( pthread_sigmask (3)) |
3616b7c0 MK |
86 | .IP \- 3 |
87 | the | |
88 | .I errno | |
89 | variable | |
90 | .IP \- 3 | |
23a6e651 | 91 | alternate signal stack |
3616b7c0 MK |
92 | .RB ( sigaltstack (2)) |
93 | .IP \- 3 | |
94 | real-time scheduling policy and priority | |
95 | .RB ( sched_setscheduler (2) | |
96 | and | |
97 | .BR sched_setparam (2)) | |
98 | .PP | |
99 | The following Linux-specific features are also per-thread: | |
100 | .IP \- 3 | |
101 | capabilities (see | |
102 | .BR capabilities (7)) | |
103 | .IP \- 3 | |
23a6e651 | 104 | CPU affinity |
3616b7c0 MK |
105 | .RB ( sched_setaffinity (2)) |
106 | .SS "Compiling on Linux" | |
107 | On Linux, programs that use the Pthreads API should be compiled using | |
4d9b6984 | 108 | .IR "cc \-pthread" . |
3616b7c0 MK |
109 | .SS "Linux Implementations of POSIX Threads" |
110 | Over time, two threading implementations have been provided by | |
111 | the GNU C library on Linux: | |
112 | .IP \- 3 | |
a5e0a0e4 | 113 | .B LinuxThreads |
3616b7c0 MK |
114 | This is the original (now obsolete) Pthreads implementation. |
115 | .IP \- 3 | |
23a6e651 | 116 | .B NPTL |
3616b7c0 MK |
117 | (Native POSIX Threads Library) |
118 | This is the modern Pthreads implementation. | |
119 | By comparison with LinuxThreads, NPTL provides closer conformance to | |
23a6e651 | 120 | the requirements of the POSIX.1 specification and better performance |
3616b7c0 | 121 | when creating large numbers of threads. |
fd064f40 | 122 | NPTL requires features that are present in the Linux 2.6 kernel. |
3616b7c0 MK |
123 | .PP |
124 | Both of these are so-called 1:1 implementations, meaning that each | |
125 | thread maps to a kernel scheduling entity. | |
126 | ||
127 | Both threading implementations employ the Linux | |
128 | .BR clone (2) | |
129 | system call. | |
d9bfdb9c | 130 | In NPTL, thread synchronization primitives (mutexes, |
3616b7c0 MK |
131 | thread joining, etc.) are implemented using the Linux |
132 | .BR futex (2) | |
133 | system call. | |
134 | .PP | |
135 | Modern GNU C libraries provide both LinuxThreads and NPTL, with the | |
136 | latter being the default (if supported by the underlying kernel). | |
137 | .SS LinuxThreads | |
138 | The notable features of this implementation are the following: | |
139 | .IP \- 3 | |
c13182ef | 140 | In addition to the main (initial) thread, |
23a6e651 | 141 | and the threads that the program creates using |
63f6a20a | 142 | .BR pthread_create (3), |
3616b7c0 MK |
143 | the implementation creates a "manager" thread. |
144 | This thread handles thread creation and termination. | |
145 | (Problems can result if this thread is inadvertently killed.) | |
146 | .IP \- 3 | |
147 | Signals are used internally by the implementation. | |
148 | On Linux 2.2 and later, the first three real-time signals are used. | |
149 | On older Linux kernels, SIGUSR1 and SIGUSR2 are used. | |
23a6e651 | 150 | Applications must avoid the use of whichever set of signals is |
3616b7c0 MK |
151 | employed by the implementation. |
152 | .IP \- 3 | |
153 | Threads do not share process IDs. | |
154 | (In effect, LinuxThreads threads are implemented as processes which share | |
155 | more information than usual, but which do not share a common process ID.) | |
156 | LinuxThreads threads (including the manager thread) | |
157 | are visible as separate processes using | |
158 | .BR ps (1). | |
159 | .PP | |
160 | The LinuxThreads implementation deviates from the POSIX.1 | |
161 | specification in a number of ways, including the following: | |
162 | .IP \- 3 | |
163 | Calls to | |
164 | .BR getpid (2) | |
165 | return a different value in each thread. | |
166 | .IP \- 3 | |
23a6e651 | 167 | Calls to |
3616b7c0 MK |
168 | .BR getppid (2) |
169 | in threads other than the main thread return the process ID of the | |
170 | manager thread; instead | |
171 | .BR getppid (2) | |
172 | in these threads should return the same value as | |
173 | .BR getppid (2) | |
174 | in the main thread. | |
175 | .IP \- 3 | |
176 | When one thread creates a new child process using | |
177 | .BR fork (2), | |
178 | any thread should be able to | |
179 | .BR wait (2) | |
180 | on the child. | |
23a6e651 | 181 | However, the implementation only allows the thread that |
3616b7c0 MK |
182 | created the child to |
183 | .BR wait (2) | |
184 | on it. | |
185 | .IP \- 3 | |
186 | When a thread calls | |
187 | .BR execve (2), | |
188 | all other threads are terminated (as required by POSIX.1). | |
189 | However, the resulting process has the same PID as the thread that called | |
190 | .BR execve (2): | |
191 | it should have the same PID as the main thread. | |
192 | .IP \- 3 | |
193 | Threads do not share user and group IDs. | |
880f5b4b | 194 | This can cause complications with set-user-ID programs and |
3616b7c0 MK |
195 | can cause failures in Pthreads functions if an application |
196 | changes its credentials using | |
197 | .BR seteuid (2) | |
198 | or similar. | |
199 | .IP \- 3 | |
200 | Threads do not share a common session ID and process group ID. | |
201 | .IP \- 3 | |
202 | Threads do not share record locks created using | |
203 | .BR fcntl (2). | |
204 | .IP \- 3 | |
205 | The information returned by | |
206 | .BR times (2) | |
207 | and | |
208 | .BR getrusage (2) | |
209 | is per-thread rather than process-wide. | |
210 | .IP \- 3 | |
211 | Threads do not share semaphore undo values (see | |
212 | .BR semop (2)). | |
213 | .IP \- 3 | |
214 | Threads do not share interval timers. | |
215 | .IP \- 3 | |
216 | Threads do not share a common nice value. | |
217 | .IP \- 3 | |
218 | POSIX.1 distinguishes the notions of signals that are directed | |
219 | to the process as a whole and signals are directed to individual | |
220 | threads. | |
221 | According to POSIX.1, a process-directed signal (sent using | |
222 | .BR kill (2), | |
223 | for example) should be handled by a single, | |
224 | arbitrarily selected thread within the process. | |
225 | LinuxThreads does not support the notion of process-directed signals: | |
226 | signals may only be sent to specific threads. | |
227 | .IP \- 3 | |
23a6e651 MK |
228 | Threads have distinct alternate signal stack settings. |
229 | However, a new thread's alternate signal stack settings | |
61f4934a | 230 | are copied from the thread that created it, so that |
23a6e651 MK |
231 | the threads initially share an alternate signal stack. |
232 | (A new thread should start with no alternate signal stack defined. | |
233 | If two threads handle signals on their shared alternate signal | |
234 | stack at the same time, unpredictable program failures are | |
235 | likely to occur.) | |
3616b7c0 MK |
236 | .SS NPTL |
237 | With NPTL, all of the threads in a process are placed | |
238 | in the same thread group; | |
239 | all members of a thread groups share the same PID. | |
23a6e651 MK |
240 | NPTL does not employ a manager thread. |
241 | NPTL makes internal use of the first two real-time signals; | |
242 | these signals cannot be used in applications. | |
243 | ||
3616b7c0 MK |
244 | NPTL still has a few non-conformances with POSIX.1: |
245 | .IP \- 3 | |
3616b7c0 | 246 | Threads do not share a common nice value. |
651946d5 MK |
247 | .\" FIXME . bug report filed for NPTL nice non-conformance |
248 | .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 | |
3616b7c0 MK |
249 | .PP |
250 | Some NPTL non-conformances only occur with older kernels: | |
251 | .IP \- 3 | |
252 | The information returned by | |
253 | .BR times (2) | |
254 | and | |
255 | .BR getrusage (2) | |
256 | is per-thread rather than process-wide (fixed in kernel 2.6.9). | |
257 | .IP \- 3 | |
258 | Threads do not share resource limits (fixed in kernel 2.6.10). | |
259 | .IP \- 3 | |
260 | Threads do not share interval timers (fixed in kernel 2.6.12). | |
2e174648 MK |
261 | .IP \- 3 |
262 | Only the main thread is permitted to start a new session using | |
263 | .BR setsid (2) | |
264 | (fixed in kernel 2.6.16). | |
265 | .IP \- 3 | |
266 | Only the main thread is permitted to make the process into a | |
267 | process group leader using | |
c13182ef | 268 | .BR setpgid (2) |
2e174648 | 269 | (fixed in kernel 2.6.16). |
456ed12f MK |
270 | .IP \- 3 |
271 | Threads have distinct alternate signal stack settings. | |
272 | However, a new thread's alternate signal stack settings | |
273 | are copied from the thread that created it, so that | |
274 | the threads initially share an alternate signal stack | |
275 | (fixed in kernel 2.6.16). | |
5e8b726f MK |
276 | .PP |
277 | Note the following further points about the NPTL implementation: | |
278 | .IP \- 3 | |
279 | If the stack size soft resource limit (see the description of | |
c13182ef | 280 | .B RLIMIT_STACK |
5e8b726f MK |
281 | in |
282 | .BR setrlimit (2)) | |
283 | is set to a value other than | |
284 | .IR unlimited , | |
285 | then this value defines the default stack size for new threads. | |
286 | To be effective, this limit must be set before the program | |
287 | is executed, perhaps using the | |
288 | .I ulimit -s | |
c13182ef | 289 | shell built-in command |
5e8b726f MK |
290 | .RI ( "limit stacksize" |
291 | in the C shell). | |
3616b7c0 | 292 | .SS "Determining the Threading Implementation" |
23a6e651 | 293 | Since glibc 2.3.2, the |
3616b7c0 MK |
294 | .BR getconf (1) |
295 | command can be used to determine | |
296 | the system's default threading implementation, for example: | |
297 | .nf | |
298 | .in +4 | |
299 | ||
300 | bash$ getconf GNU_LIBPTHREAD_VERSION | |
301 | NPTL 2.3.4 | |
302 | .in -4 | |
303 | .fi | |
304 | .PP | |
305 | With older glibc versions, a command such as the following should | |
306 | be sufficient to determine the default threading implementation: | |
307 | .nf | |
308 | .in +4 | |
309 | ||
310 | bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \\ | |
2bc2f479 | 311 | egrep \-i 'threads|ntpl' |
3616b7c0 MK |
312 | Native POSIX Threads Library by Ulrich Drepper et al |
313 | .in -4 | |
314 | .fi | |
315 | .SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL" | |
316 | On systems with a glibc that supports both LinuxThreads and NPTL, | |
317 | the LD_ASSUME_KERNEL environment variable can be used to override | |
318 | the dynamic linker's default choice of threading implementation. | |
23a6e651 | 319 | This variable tells the dynamic linker to assume that it is |
3616b7c0 MK |
320 | running on top of a particular kernel version. |
321 | By specifying a kernel version that does not | |
322 | provide the support required by NPTL, we can force the use | |
323 | of LinuxThreads. | |
324 | (The most likely reason for doing this is to run a | |
325 | (broken) application that depends on some non-conformant behavior | |
326 | in LinuxThreads.) | |
327 | For example: | |
328 | .nf | |
329 | .in +4 | |
330 | ||
331 | bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\ | |
2bc2f479 | 332 | awk '{print $3}' ) | egrep \-i 'threads|ntpl' |
3616b7c0 MK |
333 | linuxthreads-0.10 by Xavier Leroy |
334 | .in -4 | |
335 | .fi | |
336 | .SH "SEE ALSO" | |
337 | .BR clone (2), | |
338 | .BR futex (2), | |
339 | .BR gettid (2), | |
a8bda636 | 340 | .BR futex (7), |
3616b7c0 MK |
341 | and various Pthreads manual pages, for example: |
342 | .BR pthread_atfork (3), | |
343 | .BR pthread_cleanup_push (3), | |
344 | .BR pthread_cond_signal (3), | |
345 | .BR pthread_cond_wait (3), | |
346 | .BR pthread_create (3), | |
347 | .BR pthread_detach (3), | |
348 | .BR pthread_equal (3), | |
349 | .BR pthread_exit (3), | |
350 | .BR pthread_key_create (3), | |
351 | .BR pthread_kill (3), | |
352 | .BR pthread_mutex_lock (3), | |
353 | .BR pthread_mutex_unlock (3), | |
354 | .BR pthread_once (3), | |
355 | .BR pthread_setcancelstate (3), | |
356 | .BR pthread_setcanceltype (3), | |
357 | .BR pthread_setspecific (3), | |
358 | .BR pthread_sigmask (3), | |
359 | and | |
360 | .BR pthread_testcancel (3). |