]>
Commit | Line | Data |
---|---|---|
3616b7c0 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com> |
3616b7c0 MK |
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 | |
f1c71196 MK |
16 | .\" the use of the information contained herein. The author(s) may not |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
23a6e651 | 20 | .\" |
3616b7c0 MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" | |
23b98a4c | 24 | .TH PTHREADS 7 2008-05-29 "Linux" "Linux Programmer's Manual" |
3616b7c0 MK |
25 | .SH NAME |
26 | pthreads \- POSIX threads | |
27 | .SH DESCRIPTION | |
23a6e651 | 28 | POSIX.1 specifies a set of interfaces (functions, header files) for |
3616b7c0 | 29 | threaded programming commonly known as POSIX threads, or Pthreads. |
23a6e651 | 30 | A single process can contain multiple threads, |
3616b7c0 MK |
31 | all of which are executing the same program. |
32 | These threads share the same global memory (data and heap segments), | |
33 | but each thread has its own stack (automatic variables). | |
34 | ||
35 | POSIX.1 also requires that threads share a range of other attributes | |
36 | (i.e., these attributes are process-wide rather than per-thread): | |
37 | .IP \- 3 | |
38 | process ID | |
39 | .IP \- 3 | |
40 | parent process ID | |
41 | .IP \- 3 | |
42 | process group ID and session ID | |
43 | .IP \- 3 | |
44 | controlling terminal | |
45 | .IP \- 3 | |
46 | user and group IDs | |
47 | .IP \- 3 | |
48 | open file descriptors | |
49 | .IP \- 3 | |
50 | record locks (see | |
51 | .BR fcntl (2)) | |
52 | .IP \- 3 | |
53 | signal dispositions | |
54 | .IP \- 3 | |
55 | file mode creation mask | |
56 | .RB ( umask (2)) | |
57 | .IP \- 3 | |
23a6e651 | 58 | current directory |
3616b7c0 MK |
59 | .RB ( chdir (2)) |
60 | and | |
61 | root directory | |
62 | .RB ( chroot (2)) | |
63 | .IP \- 3 | |
64 | interval timers | |
65 | .RB ( setitimer (2)) | |
66 | and POSIX timers | |
63f6a20a | 67 | .RB ( timer_create (3)) |
3616b7c0 MK |
68 | .IP \- 3 |
69 | nice value | |
70 | .RB ( setpriority (2)) | |
71 | .IP \- 3 | |
72 | resource limits | |
73 | .RB ( setrlimit (2)) | |
74 | .IP \- 3 | |
23a6e651 | 75 | measurements of the consumption of CPU time |
3616b7c0 | 76 | .RB ( times (2)) |
23a6e651 | 77 | and resources |
3616b7c0 MK |
78 | .RB ( getrusage (2)) |
79 | .PP | |
80 | As well as the stack, POSIX.1 specifies that various other | |
81 | attributes are distinct for each thread, including: | |
82 | .IP \- 3 | |
83 | thread ID (the | |
84 | .I pthread_t | |
85 | data type) | |
86 | .IP \- 3 | |
87 | signal mask | |
63f6a20a | 88 | .RB ( pthread_sigmask (3)) |
3616b7c0 MK |
89 | .IP \- 3 |
90 | the | |
91 | .I errno | |
92 | variable | |
93 | .IP \- 3 | |
23a6e651 | 94 | alternate signal stack |
3616b7c0 MK |
95 | .RB ( sigaltstack (2)) |
96 | .IP \- 3 | |
97 | real-time scheduling policy and priority | |
98 | .RB ( sched_setscheduler (2) | |
99 | and | |
100 | .BR sched_setparam (2)) | |
101 | .PP | |
102 | The following Linux-specific features are also per-thread: | |
103 | .IP \- 3 | |
104 | capabilities (see | |
105 | .BR capabilities (7)) | |
106 | .IP \- 3 | |
23a6e651 | 107 | CPU affinity |
3616b7c0 | 108 | .RB ( sched_setaffinity (2)) |
0d07ad30 MK |
109 | .SS "Thread-safe functions" |
110 | A thread-safe function is one that can be safely | |
111 | (i.e., it will deliver the same results regardless of whether it is) | |
112 | called from multiple threads at the same time. | |
113 | ||
114 | POSIX.1-2001 requires that all functions specified in the standard | |
115 | shall be thread-safe, except for the following functions: | |
116 | .\" FIXME . SUSv4 removes ecvt(), fcvt(), gcvt(), gethostbyname(), and | |
117 | .\" gethostbyaddr(), since they are removed from the standard, and | |
118 | .\" and adds strerror() and system(). | |
119 | .in +4n | |
120 | .nf | |
121 | ||
122 | asctime() | |
123 | basename() | |
124 | catgets() | |
125 | crypt() | |
126 | ctermid() if passed a non-NULL argument | |
127 | ctime() | |
128 | dbm_clearerr() | |
129 | dbm_close() | |
130 | dbm_delete() | |
131 | dbm_error() | |
132 | dbm_fetch() | |
133 | dbm_firstkey() | |
134 | dbm_nextkey() | |
135 | dbm_open() | |
136 | dbm_store() | |
137 | dirname() | |
138 | dlerror() | |
139 | drand48() | |
140 | ecvt() | |
141 | encrypt() | |
142 | endgrent() | |
143 | endpwent() | |
144 | endutxent() | |
145 | fcvt() | |
146 | ftw() | |
147 | gcvt() | |
148 | getc_unlocked() | |
149 | getchar_unlocked() | |
150 | getdate() | |
151 | getenv() | |
152 | getgrent() | |
153 | getgrgid() | |
154 | getgrnam() | |
155 | gethostbyaddr() | |
156 | gethostbyname() | |
157 | gethostent() | |
158 | getlogin() | |
159 | getnetbyaddr() | |
160 | getnetbyname() | |
161 | getnetent() | |
162 | getopt() | |
163 | getprotobyname() | |
164 | getprotobynumber() | |
165 | getprotoent() | |
166 | getpwent() | |
167 | getpwnam() | |
168 | getpwuid() | |
169 | getservbyname() | |
170 | getservbyport() | |
171 | getservent() | |
172 | getutxent() | |
173 | getutxid() | |
174 | getutxline() | |
175 | gmtime() | |
176 | hcreate() | |
177 | hdestroy() | |
178 | hsearch() | |
179 | inet_ntoa() | |
180 | l64a() | |
181 | lgamma() | |
182 | lgammaf() | |
183 | lgammal() | |
184 | localeconv() | |
185 | localtime() | |
186 | lrand48() | |
187 | mrand48() | |
188 | nftw() | |
189 | nl_langinfo() | |
190 | ptsname() | |
191 | putc_unlocked() | |
192 | putchar_unlocked() | |
193 | putenv() | |
194 | pututxline() | |
195 | rand() | |
196 | readdir() | |
197 | setenv() | |
198 | setgrent() | |
199 | setkey() | |
200 | setpwent() | |
201 | setutxent() | |
202 | strerror() | |
203 | strtok() | |
204 | tmpnam() if passed a non-NULL argument | |
205 | ttyname() | |
206 | unsetenv() | |
207 | wcrtomb() if its final argument is NULL | |
208 | wcsrtombs() if its final argument is NULL | |
209 | wcstombs() | |
210 | wctomb() | |
211 | .fi | |
212 | .in | |
3616b7c0 MK |
213 | .SS "Compiling on Linux" |
214 | On Linux, programs that use the Pthreads API should be compiled using | |
4d9b6984 | 215 | .IR "cc \-pthread" . |
3616b7c0 MK |
216 | .SS "Linux Implementations of POSIX Threads" |
217 | Over time, two threading implementations have been provided by | |
218 | the GNU C library on Linux: | |
ffe649e9 | 219 | .TP |
a5e0a0e4 | 220 | .B LinuxThreads |
9bc64d3e MK |
221 | This is the original Pthreads implementation. |
222 | Since glibc 2.4, this implementation is no longer supported. | |
ffe649e9 MK |
223 | .TP |
224 | .BR NPTL " (Native POSIX Threads Library)" | |
3616b7c0 MK |
225 | This is the modern Pthreads implementation. |
226 | By comparison with LinuxThreads, NPTL provides closer conformance to | |
23a6e651 | 227 | the requirements of the POSIX.1 specification and better performance |
3616b7c0 | 228 | when creating large numbers of threads. |
9bc64d3e MK |
229 | NPTL is available since glibc 2.3.2, |
230 | and requires features that are present in the Linux 2.6 kernel. | |
3616b7c0 MK |
231 | .PP |
232 | Both of these are so-called 1:1 implementations, meaning that each | |
233 | thread maps to a kernel scheduling entity. | |
3616b7c0 MK |
234 | Both threading implementations employ the Linux |
235 | .BR clone (2) | |
236 | system call. | |
d9bfdb9c | 237 | In NPTL, thread synchronization primitives (mutexes, |
3616b7c0 MK |
238 | thread joining, etc.) are implemented using the Linux |
239 | .BR futex (2) | |
240 | system call. | |
3616b7c0 MK |
241 | .SS LinuxThreads |
242 | The notable features of this implementation are the following: | |
243 | .IP \- 3 | |
c13182ef | 244 | In addition to the main (initial) thread, |
23a6e651 | 245 | and the threads that the program creates using |
63f6a20a | 246 | .BR pthread_create (3), |
3616b7c0 MK |
247 | the implementation creates a "manager" thread. |
248 | This thread handles thread creation and termination. | |
249 | (Problems can result if this thread is inadvertently killed.) | |
250 | .IP \- 3 | |
251 | Signals are used internally by the implementation. | |
252 | On Linux 2.2 and later, the first three real-time signals are used. | |
8bd58774 MK |
253 | On older Linux kernels, |
254 | .B SIGUSR1 | |
255 | and | |
256 | .B SIGUSR2 | |
257 | are used. | |
23a6e651 | 258 | Applications must avoid the use of whichever set of signals is |
3616b7c0 MK |
259 | employed by the implementation. |
260 | .IP \- 3 | |
261 | Threads do not share process IDs. | |
262 | (In effect, LinuxThreads threads are implemented as processes which share | |
263 | more information than usual, but which do not share a common process ID.) | |
264 | LinuxThreads threads (including the manager thread) | |
265 | are visible as separate processes using | |
266 | .BR ps (1). | |
267 | .PP | |
268 | The LinuxThreads implementation deviates from the POSIX.1 | |
269 | specification in a number of ways, including the following: | |
270 | .IP \- 3 | |
271 | Calls to | |
272 | .BR getpid (2) | |
273 | return a different value in each thread. | |
274 | .IP \- 3 | |
23a6e651 | 275 | Calls to |
3616b7c0 MK |
276 | .BR getppid (2) |
277 | in threads other than the main thread return the process ID of the | |
278 | manager thread; instead | |
279 | .BR getppid (2) | |
280 | in these threads should return the same value as | |
281 | .BR getppid (2) | |
282 | in the main thread. | |
283 | .IP \- 3 | |
284 | When one thread creates a new child process using | |
285 | .BR fork (2), | |
286 | any thread should be able to | |
287 | .BR wait (2) | |
288 | on the child. | |
23a6e651 | 289 | However, the implementation only allows the thread that |
3616b7c0 MK |
290 | created the child to |
291 | .BR wait (2) | |
292 | on it. | |
293 | .IP \- 3 | |
294 | When a thread calls | |
295 | .BR execve (2), | |
296 | all other threads are terminated (as required by POSIX.1). | |
297 | However, the resulting process has the same PID as the thread that called | |
298 | .BR execve (2): | |
299 | it should have the same PID as the main thread. | |
300 | .IP \- 3 | |
301 | Threads do not share user and group IDs. | |
880f5b4b | 302 | This can cause complications with set-user-ID programs and |
3616b7c0 MK |
303 | can cause failures in Pthreads functions if an application |
304 | changes its credentials using | |
305 | .BR seteuid (2) | |
306 | or similar. | |
307 | .IP \- 3 | |
308 | Threads do not share a common session ID and process group ID. | |
309 | .IP \- 3 | |
310 | Threads do not share record locks created using | |
311 | .BR fcntl (2). | |
312 | .IP \- 3 | |
313 | The information returned by | |
314 | .BR times (2) | |
315 | and | |
316 | .BR getrusage (2) | |
317 | is per-thread rather than process-wide. | |
318 | .IP \- 3 | |
319 | Threads do not share semaphore undo values (see | |
320 | .BR semop (2)). | |
321 | .IP \- 3 | |
322 | Threads do not share interval timers. | |
323 | .IP \- 3 | |
324 | Threads do not share a common nice value. | |
325 | .IP \- 3 | |
326 | POSIX.1 distinguishes the notions of signals that are directed | |
a7e7c7fc | 327 | to the process as a whole and signals that are directed to individual |
3616b7c0 MK |
328 | threads. |
329 | According to POSIX.1, a process-directed signal (sent using | |
330 | .BR kill (2), | |
331 | for example) should be handled by a single, | |
332 | arbitrarily selected thread within the process. | |
333 | LinuxThreads does not support the notion of process-directed signals: | |
334 | signals may only be sent to specific threads. | |
335 | .IP \- 3 | |
23a6e651 MK |
336 | Threads have distinct alternate signal stack settings. |
337 | However, a new thread's alternate signal stack settings | |
61f4934a | 338 | are copied from the thread that created it, so that |
23a6e651 MK |
339 | the threads initially share an alternate signal stack. |
340 | (A new thread should start with no alternate signal stack defined. | |
341 | If two threads handle signals on their shared alternate signal | |
342 | stack at the same time, unpredictable program failures are | |
343 | likely to occur.) | |
3616b7c0 MK |
344 | .SS NPTL |
345 | With NPTL, all of the threads in a process are placed | |
346 | in the same thread group; | |
347 | all members of a thread groups share the same PID. | |
23a6e651 MK |
348 | NPTL does not employ a manager thread. |
349 | NPTL makes internal use of the first two real-time signals; | |
350 | these signals cannot be used in applications. | |
351 | ||
ffe649e9 | 352 | NPTL still has at least one non-conformance with POSIX.1: |
3616b7c0 | 353 | .IP \- 3 |
3616b7c0 | 354 | Threads do not share a common nice value. |
651946d5 MK |
355 | .\" FIXME . bug report filed for NPTL nice non-conformance |
356 | .\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 | |
3616b7c0 MK |
357 | .PP |
358 | Some NPTL non-conformances only occur with older kernels: | |
359 | .IP \- 3 | |
360 | The information returned by | |
361 | .BR times (2) | |
362 | and | |
363 | .BR getrusage (2) | |
364 | is per-thread rather than process-wide (fixed in kernel 2.6.9). | |
365 | .IP \- 3 | |
366 | Threads do not share resource limits (fixed in kernel 2.6.10). | |
367 | .IP \- 3 | |
368 | Threads do not share interval timers (fixed in kernel 2.6.12). | |
2e174648 MK |
369 | .IP \- 3 |
370 | Only the main thread is permitted to start a new session using | |
371 | .BR setsid (2) | |
372 | (fixed in kernel 2.6.16). | |
373 | .IP \- 3 | |
374 | Only the main thread is permitted to make the process into a | |
375 | process group leader using | |
c13182ef | 376 | .BR setpgid (2) |
2e174648 | 377 | (fixed in kernel 2.6.16). |
456ed12f MK |
378 | .IP \- 3 |
379 | Threads have distinct alternate signal stack settings. | |
380 | However, a new thread's alternate signal stack settings | |
381 | are copied from the thread that created it, so that | |
382 | the threads initially share an alternate signal stack | |
383 | (fixed in kernel 2.6.16). | |
5e8b726f MK |
384 | .PP |
385 | Note the following further points about the NPTL implementation: | |
386 | .IP \- 3 | |
387 | If the stack size soft resource limit (see the description of | |
c13182ef | 388 | .B RLIMIT_STACK |
5e8b726f MK |
389 | in |
390 | .BR setrlimit (2)) | |
391 | is set to a value other than | |
392 | .IR unlimited , | |
393 | then this value defines the default stack size for new threads. | |
394 | To be effective, this limit must be set before the program | |
395 | is executed, perhaps using the | |
396 | .I ulimit -s | |
c13182ef | 397 | shell built-in command |
5e8b726f MK |
398 | .RI ( "limit stacksize" |
399 | in the C shell). | |
3616b7c0 | 400 | .SS "Determining the Threading Implementation" |
23a6e651 | 401 | Since glibc 2.3.2, the |
3616b7c0 MK |
402 | .BR getconf (1) |
403 | command can be used to determine | |
9bc64d3e | 404 | the system's threading implementation, for example: |
3616b7c0 | 405 | .nf |
088a639b | 406 | .in +4n |
3616b7c0 MK |
407 | |
408 | bash$ getconf GNU_LIBPTHREAD_VERSION | |
409 | NPTL 2.3.4 | |
088a639b | 410 | .in |
3616b7c0 MK |
411 | .fi |
412 | .PP | |
413 | With older glibc versions, a command such as the following should | |
414 | be sufficient to determine the default threading implementation: | |
415 | .nf | |
088a639b | 416 | .in +4n |
3616b7c0 | 417 | |
f81fb444 MK |
418 | bash$ $( ldd /bin/ls | grep libc.so | awk \(aq{print $3}\(aq ) | \\ |
419 | egrep \-i \(aqthreads|nptl\(aq | |
3616b7c0 | 420 | Native POSIX Threads Library by Ulrich Drepper et al |
088a639b | 421 | .in |
3616b7c0 MK |
422 | .fi |
423 | .SS "Selecting the Threading Implementation: LD_ASSUME_KERNEL" | |
9bc64d3e MK |
424 | On systems with a glibc that supports both LinuxThreads and NPTL |
425 | (i.e., glibc 2.3.\fIx\fP), the | |
097585ed MK |
426 | .B LD_ASSUME_KERNEL |
427 | environment variable can be used to override | |
3616b7c0 | 428 | the dynamic linker's default choice of threading implementation. |
23a6e651 | 429 | This variable tells the dynamic linker to assume that it is |
3616b7c0 MK |
430 | running on top of a particular kernel version. |
431 | By specifying a kernel version that does not | |
432 | provide the support required by NPTL, we can force the use | |
433 | of LinuxThreads. | |
434 | (The most likely reason for doing this is to run a | |
435 | (broken) application that depends on some non-conformant behavior | |
436 | in LinuxThreads.) | |
437 | For example: | |
438 | .nf | |
088a639b | 439 | .in +4n |
3616b7c0 MK |
440 | |
441 | bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \\ | |
f81fb444 | 442 | awk \(aq{print $3}\(aq ) | egrep \-i \(aqthreads|ntpl\(aq |
3616b7c0 | 443 | linuxthreads-0.10 by Xavier Leroy |
088a639b | 444 | .in |
3616b7c0 MK |
445 | .fi |
446 | .SH "SEE ALSO" | |
447 | .BR clone (2), | |
448 | .BR futex (2), | |
449 | .BR gettid (2), | |
a8bda636 | 450 | .BR futex (7), |
f0c34053 | 451 | .br |
3616b7c0 MK |
452 | and various Pthreads manual pages, for example: |
453 | .BR pthread_atfork (3), | |
454 | .BR pthread_cleanup_push (3), | |
455 | .BR pthread_cond_signal (3), | |
456 | .BR pthread_cond_wait (3), | |
457 | .BR pthread_create (3), | |
458 | .BR pthread_detach (3), | |
459 | .BR pthread_equal (3), | |
460 | .BR pthread_exit (3), | |
461 | .BR pthread_key_create (3), | |
462 | .BR pthread_kill (3), | |
463 | .BR pthread_mutex_lock (3), | |
464 | .BR pthread_mutex_unlock (3), | |
465 | .BR pthread_once (3), | |
466 | .BR pthread_setcancelstate (3), | |
467 | .BR pthread_setcanceltype (3), | |
468 | .BR pthread_setspecific (3), | |
469 | .BR pthread_sigmask (3), | |
470 | and | |
f0c34053 | 471 | .BR pthread_testcancel (3) |