]>
Commit | Line | Data |
---|---|---|
3616b7c0 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com> |
3616b7c0 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
3616b7c0 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
23a6e651 | 13 | .\" |
3616b7c0 MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
f1c71196 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
23a6e651 | 21 | .\" |
3616b7c0 MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
3616b7c0 | 25 | .\" |
9ba01802 | 26 | .TH PTHREADS 7 2019-03-06 "Linux" "Linux Programmer's Manual" |
3616b7c0 MK |
27 | .SH NAME |
28 | pthreads \- POSIX threads | |
29 | .SH DESCRIPTION | |
23a6e651 | 30 | POSIX.1 specifies a set of interfaces (functions, header files) for |
3616b7c0 | 31 | threaded programming commonly known as POSIX threads, or Pthreads. |
23a6e651 | 32 | A single process can contain multiple threads, |
3616b7c0 MK |
33 | all of which are executing the same program. |
34 | These threads share the same global memory (data and heap segments), | |
35 | but each thread has its own stack (automatic variables). | |
a721e8b2 | 36 | .PP |
3616b7c0 MK |
37 | POSIX.1 also requires that threads share a range of other attributes |
38 | (i.e., these attributes are process-wide rather than per-thread): | |
39 | .IP \- 3 | |
40 | process ID | |
41 | .IP \- 3 | |
42 | parent process ID | |
43 | .IP \- 3 | |
44 | process group ID and session ID | |
45 | .IP \- 3 | |
46 | controlling terminal | |
47 | .IP \- 3 | |
48 | user and group IDs | |
49 | .IP \- 3 | |
50 | open file descriptors | |
51 | .IP \- 3 | |
52 | record locks (see | |
53 | .BR fcntl (2)) | |
54 | .IP \- 3 | |
55 | signal dispositions | |
56 | .IP \- 3 | |
57 | file mode creation mask | |
58 | .RB ( umask (2)) | |
59 | .IP \- 3 | |
23a6e651 | 60 | current directory |
3616b7c0 MK |
61 | .RB ( chdir (2)) |
62 | and | |
63 | root directory | |
64 | .RB ( chroot (2)) | |
65 | .IP \- 3 | |
66 | interval timers | |
67 | .RB ( setitimer (2)) | |
68 | and POSIX timers | |
804f03e6 | 69 | .RB ( timer_create (2)) |
3616b7c0 MK |
70 | .IP \- 3 |
71 | nice value | |
72 | .RB ( setpriority (2)) | |
73 | .IP \- 3 | |
74 | resource limits | |
75 | .RB ( setrlimit (2)) | |
76 | .IP \- 3 | |
23a6e651 | 77 | measurements of the consumption of CPU time |
3616b7c0 | 78 | .RB ( times (2)) |
23a6e651 | 79 | and resources |
3616b7c0 MK |
80 | .RB ( getrusage (2)) |
81 | .PP | |
82 | As well as the stack, POSIX.1 specifies that various other | |
83 | attributes are distinct for each thread, including: | |
84 | .IP \- 3 | |
85 | thread ID (the | |
86 | .I pthread_t | |
87 | data type) | |
88 | .IP \- 3 | |
89 | signal mask | |
63f6a20a | 90 | .RB ( pthread_sigmask (3)) |
3616b7c0 MK |
91 | .IP \- 3 |
92 | the | |
93 | .I errno | |
94 | variable | |
95 | .IP \- 3 | |
23a6e651 | 96 | alternate signal stack |
3616b7c0 MK |
97 | .RB ( sigaltstack (2)) |
98 | .IP \- 3 | |
99 | real-time scheduling policy and priority | |
25ac8173 | 100 | .RB ( sched (7)) |
3616b7c0 MK |
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)) |
73d8cece | 109 | .SS Pthreads function return values |
dad5081f | 110 | Most pthreads functions return 0 on success, and an error number on failure. |
63c22325 MK |
111 | Note that the pthreads functions do not set |
112 | .IR errno . | |
113 | For each of the pthreads functions that can return an error, | |
114 | POSIX.1-2001 specifies that the function can never fail with the error | |
115 | .BR EINTR . | |
84ee6c22 MK |
116 | .SS Thread IDs |
117 | Each of the threads in a process has a unique thread identifier | |
118 | (stored in the type | |
119 | .IR pthread_t ). | |
120 | This identifier is returned to the caller of | |
121 | .BR pthread_create (3), | |
122 | and a thread can obtain its own thread identifier using | |
123 | .BR pthread_self (3). | |
a721e8b2 | 124 | .PP |
33a0ccb2 | 125 | Thread IDs are guaranteed to be unique only within a process. |
0ad13546 MK |
126 | (In all pthreads functions that accept a thread ID as an argument, |
127 | that ID by definition refers to a thread in | |
128 | the same process as the caller.) | |
a721e8b2 | 129 | .PP |
ccbcc0ae | 130 | The system may reuse a thread ID after a terminated thread has been joined, |
84ee6c22 | 131 | or a detached thread has terminated. |
ccbcc0ae MK |
132 | POSIX says: "If an application attempts to use a thread ID whose |
133 | lifetime has ended, the behavior is undefined." | |
73d8cece | 134 | .SS Thread-safe functions |
0d07ad30 MK |
135 | A thread-safe function is one that can be safely |
136 | (i.e., it will deliver the same results regardless of whether it is) | |
137 | called from multiple threads at the same time. | |
a721e8b2 | 138 | .PP |
447cd9e7 MK |
139 | POSIX.1-2001 and POSIX.1-2008 require that all functions specified |
140 | in the standard shall be thread-safe, | |
141 | except for the following functions: | |
e646a1ba | 142 | .PP |
0d07ad30 | 143 | .in +4n |
e646a1ba | 144 | .EX |
0d07ad30 MK |
145 | asctime() |
146 | basename() | |
147 | catgets() | |
148 | crypt() | |
149 | ctermid() if passed a non-NULL argument | |
150 | ctime() | |
151 | dbm_clearerr() | |
152 | dbm_close() | |
153 | dbm_delete() | |
154 | dbm_error() | |
155 | dbm_fetch() | |
156 | dbm_firstkey() | |
157 | dbm_nextkey() | |
158 | dbm_open() | |
159 | dbm_store() | |
160 | dirname() | |
161 | dlerror() | |
162 | drand48() | |
447cd9e7 | 163 | ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
0d07ad30 MK |
164 | encrypt() |
165 | endgrent() | |
166 | endpwent() | |
167 | endutxent() | |
447cd9e7 | 168 | fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
0d07ad30 | 169 | ftw() |
447cd9e7 | 170 | gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
0d07ad30 MK |
171 | getc_unlocked() |
172 | getchar_unlocked() | |
173 | getdate() | |
174 | getenv() | |
175 | getgrent() | |
176 | getgrgid() | |
177 | getgrnam() | |
447cd9e7 MK |
178 | gethostbyaddr() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
179 | gethostbyname() [POSIX.1-2001 only (function removed in POSIX.1-2008)] | |
0d07ad30 MK |
180 | gethostent() |
181 | getlogin() | |
182 | getnetbyaddr() | |
183 | getnetbyname() | |
184 | getnetent() | |
185 | getopt() | |
186 | getprotobyname() | |
187 | getprotobynumber() | |
188 | getprotoent() | |
189 | getpwent() | |
190 | getpwnam() | |
191 | getpwuid() | |
192 | getservbyname() | |
193 | getservbyport() | |
194 | getservent() | |
195 | getutxent() | |
196 | getutxid() | |
197 | getutxline() | |
198 | gmtime() | |
199 | hcreate() | |
200 | hdestroy() | |
201 | hsearch() | |
202 | inet_ntoa() | |
203 | l64a() | |
204 | lgamma() | |
205 | lgammaf() | |
206 | lgammal() | |
207 | localeconv() | |
208 | localtime() | |
209 | lrand48() | |
210 | mrand48() | |
211 | nftw() | |
212 | nl_langinfo() | |
213 | ptsname() | |
214 | putc_unlocked() | |
215 | putchar_unlocked() | |
216 | putenv() | |
217 | pututxline() | |
218 | rand() | |
219 | readdir() | |
220 | setenv() | |
221 | setgrent() | |
222 | setkey() | |
223 | setpwent() | |
224 | setutxent() | |
225 | strerror() | |
447cd9e7 | 226 | strsignal() [Added in POSIX.1-2008] |
0d07ad30 | 227 | strtok() |
447cd9e7 | 228 | system() [Added in POSIX.1-2008] |
0d07ad30 MK |
229 | tmpnam() if passed a non-NULL argument |
230 | ttyname() | |
231 | unsetenv() | |
232 | wcrtomb() if its final argument is NULL | |
233 | wcsrtombs() if its final argument is NULL | |
234 | wcstombs() | |
235 | wctomb() | |
b8302363 | 236 | .EE |
0d07ad30 | 237 | .in |
07451ab1 MK |
238 | .SS Async-cancel-safe functions |
239 | An async-cancel-safe function is one that can be safely called | |
240 | in an application where asynchronous cancelability is enabled (see | |
241 | .BR pthread_setcancelstate (3)). | |
a721e8b2 | 242 | .PP |
07451ab1 MK |
243 | Only the following functions are required to be async-cancel-safe by |
244 | POSIX.1-2001 and POSIX.1-2008: | |
e646a1ba | 245 | .PP |
07451ab1 | 246 | .in +4n |
e646a1ba | 247 | .EX |
07451ab1 MK |
248 | pthread_cancel() |
249 | pthread_setcancelstate() | |
250 | pthread_setcanceltype() | |
b8302363 | 251 | .EE |
07451ab1 | 252 | .in |
c634028a | 253 | .SS Cancellation points |
ffe8c4ae MK |
254 | POSIX.1 specifies that certain functions must, |
255 | and certain other functions may, be cancellation points. | |
256 | If a thread is cancelable, its cancelability type is deferred, | |
257 | and a cancellation request is pending for the thread, | |
258 | then the thread is canceled when it calls a function | |
259 | that is a cancellation point. | |
a721e8b2 | 260 | .PP |
ffe8c4ae MK |
261 | The following functions are required to be cancellation points by |
262 | POSIX.1-2001 and/or POSIX.1-2008: | |
a721e8b2 | 263 | .PP |
7aaa4c67 MK |
264 | .\" FIXME |
265 | .\" Document the list of all functions that are cancellation points in glibc | |
ffe8c4ae | 266 | .in +4n |
b8302363 | 267 | .EX |
ffe8c4ae MK |
268 | accept() |
269 | aio_suspend() | |
270 | clock_nanosleep() | |
271 | close() | |
272 | connect() | |
273 | creat() | |
274 | fcntl() F_SETLKW | |
275 | fdatasync() | |
276 | fsync() | |
277 | getmsg() | |
278 | getpmsg() | |
279 | lockf() F_LOCK | |
280 | mq_receive() | |
281 | mq_send() | |
282 | mq_timedreceive() | |
283 | mq_timedsend() | |
284 | msgrcv() | |
285 | msgsnd() | |
286 | msync() | |
287 | nanosleep() | |
288 | open() | |
289 | openat() [Added in POSIX.1-2008] | |
290 | pause() | |
291 | poll() | |
292 | pread() | |
293 | pselect() | |
294 | pthread_cond_timedwait() | |
295 | pthread_cond_wait() | |
296 | pthread_join() | |
297 | pthread_testcancel() | |
298 | putmsg() | |
299 | putpmsg() | |
300 | pwrite() | |
301 | read() | |
302 | readv() | |
303 | recv() | |
304 | recvfrom() | |
305 | recvmsg() | |
306 | select() | |
307 | sem_timedwait() | |
308 | sem_wait() | |
309 | send() | |
310 | sendmsg() | |
311 | sendto() | |
7fd4e74c | 312 | sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)] |
ffe8c4ae MK |
313 | sigsuspend() |
314 | sigtimedwait() | |
315 | sigwait() | |
316 | sigwaitinfo() | |
317 | sleep() | |
318 | system() | |
319 | tcdrain() | |
320 | usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)] | |
321 | wait() | |
322 | waitid() | |
323 | waitpid() | |
324 | write() | |
325 | writev() | |
b8302363 | 326 | .EE |
ffe8c4ae | 327 | .in |
a721e8b2 | 328 | .PP |
ffe8c4ae MK |
329 | The following functions may be cancellation points according to |
330 | POSIX.1-2001 and/or POSIX.1-2008: | |
a721e8b2 | 331 | .PP |
ffe8c4ae | 332 | .in +4n |
b8302363 | 333 | .EX |
ffe8c4ae MK |
334 | access() |
335 | asctime() | |
336 | asctime_r() | |
337 | catclose() | |
338 | catgets() | |
339 | catopen() | |
340 | chmod() [Added in POSIX.1-2008] | |
341 | chown() [Added in POSIX.1-2008] | |
342 | closedir() | |
343 | closelog() | |
344 | ctermid() | |
345 | ctime() | |
346 | ctime_r() | |
347 | dbm_close() | |
348 | dbm_delete() | |
349 | dbm_fetch() | |
350 | dbm_nextkey() | |
351 | dbm_open() | |
352 | dbm_store() | |
353 | dlclose() | |
354 | dlopen() | |
355 | dprintf() [Added in POSIX.1-2008] | |
356 | endgrent() | |
357 | endhostent() | |
358 | endnetent() | |
359 | endprotoent() | |
360 | endpwent() | |
361 | endservent() | |
362 | endutxent() | |
363 | faccessat() [Added in POSIX.1-2008] | |
364 | fchmod() [Added in POSIX.1-2008] | |
365 | fchmodat() [Added in POSIX.1-2008] | |
366 | fchown() [Added in POSIX.1-2008] | |
367 | fchownat() [Added in POSIX.1-2008] | |
368 | fclose() | |
369 | fcntl() (for any value of cmd argument) | |
370 | fflush() | |
371 | fgetc() | |
372 | fgetpos() | |
373 | fgets() | |
374 | fgetwc() | |
375 | fgetws() | |
376 | fmtmsg() | |
377 | fopen() | |
378 | fpathconf() | |
379 | fprintf() | |
380 | fputc() | |
381 | fputs() | |
382 | fputwc() | |
383 | fputws() | |
384 | fread() | |
385 | freopen() | |
386 | fscanf() | |
387 | fseek() | |
388 | fseeko() | |
389 | fsetpos() | |
390 | fstat() | |
391 | fstatat() [Added in POSIX.1-2008] | |
392 | ftell() | |
393 | ftello() | |
394 | ftw() | |
395 | futimens() [Added in POSIX.1-2008] | |
396 | fwprintf() | |
397 | fwrite() | |
398 | fwscanf() | |
399 | getaddrinfo() | |
400 | getc() | |
401 | getc_unlocked() | |
402 | getchar() | |
403 | getchar_unlocked() | |
404 | getcwd() | |
405 | getdate() | |
406 | getdelim() [Added in POSIX.1-2008] | |
407 | getgrent() | |
408 | getgrgid() | |
409 | getgrgid_r() | |
410 | getgrnam() | |
411 | getgrnam_r() | |
412 | gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)] | |
413 | gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)] | |
414 | gethostent() | |
415 | gethostid() | |
416 | gethostname() | |
417 | getline() [Added in POSIX.1-2008] | |
418 | getlogin() | |
419 | getlogin_r() | |
420 | getnameinfo() | |
421 | getnetbyaddr() | |
422 | getnetbyname() | |
423 | getnetent() | |
c7094399 | 424 | getopt() (if opterr is nonzero) |
ffe8c4ae MK |
425 | getprotobyname() |
426 | getprotobynumber() | |
427 | getprotoent() | |
428 | getpwent() | |
429 | getpwnam() | |
430 | getpwnam_r() | |
431 | getpwuid() | |
432 | getpwuid_r() | |
433 | gets() | |
434 | getservbyname() | |
435 | getservbyport() | |
436 | getservent() | |
437 | getutxent() | |
438 | getutxid() | |
439 | getutxline() | |
440 | getwc() | |
441 | getwchar() | |
442 | getwd() [SUSv3 only (function removed in POSIX.1-2008)] | |
443 | glob() | |
444 | iconv_close() | |
445 | iconv_open() | |
446 | ioctl() | |
447 | link() | |
448 | linkat() [Added in POSIX.1-2008] | |
449 | lio_listio() [Added in POSIX.1-2008] | |
450 | localtime() | |
451 | localtime_r() | |
452 | lockf() [Added in POSIX.1-2008] | |
453 | lseek() | |
454 | lstat() | |
455 | mkdir() [Added in POSIX.1-2008] | |
456 | mkdirat() [Added in POSIX.1-2008] | |
457 | mkdtemp() [Added in POSIX.1-2008] | |
458 | mkfifo() [Added in POSIX.1-2008] | |
459 | mkfifoat() [Added in POSIX.1-2008] | |
460 | mknod() [Added in POSIX.1-2008] | |
461 | mknodat() [Added in POSIX.1-2008] | |
462 | mkstemp() | |
463 | mktime() | |
464 | nftw() | |
465 | opendir() | |
466 | openlog() | |
467 | pathconf() | |
468 | pclose() | |
469 | perror() | |
470 | popen() | |
471 | posix_fadvise() | |
472 | posix_fallocate() | |
473 | posix_madvise() | |
474 | posix_openpt() | |
475 | posix_spawn() | |
476 | posix_spawnp() | |
477 | posix_trace_clear() | |
478 | posix_trace_close() | |
479 | posix_trace_create() | |
480 | posix_trace_create_withlog() | |
481 | posix_trace_eventtypelist_getnext_id() | |
482 | posix_trace_eventtypelist_rewind() | |
483 | posix_trace_flush() | |
484 | posix_trace_get_attr() | |
485 | posix_trace_get_filter() | |
486 | posix_trace_get_status() | |
487 | posix_trace_getnext_event() | |
488 | posix_trace_open() | |
489 | posix_trace_rewind() | |
490 | posix_trace_set_filter() | |
491 | posix_trace_shutdown() | |
492 | posix_trace_timedgetnext_event() | |
493 | posix_typed_mem_open() | |
494 | printf() | |
495 | psiginfo() [Added in POSIX.1-2008] | |
496 | psignal() [Added in POSIX.1-2008] | |
497 | pthread_rwlock_rdlock() | |
498 | pthread_rwlock_timedrdlock() | |
499 | pthread_rwlock_timedwrlock() | |
500 | pthread_rwlock_wrlock() | |
501 | putc() | |
502 | putc_unlocked() | |
503 | putchar() | |
504 | putchar_unlocked() | |
505 | puts() | |
506 | pututxline() | |
507 | putwc() | |
508 | putwchar() | |
509 | readdir() | |
510 | readdir_r() | |
511 | readlink() [Added in POSIX.1-2008] | |
512 | readlinkat() [Added in POSIX.1-2008] | |
513 | remove() | |
514 | rename() | |
515 | renameat() [Added in POSIX.1-2008] | |
516 | rewind() | |
517 | rewinddir() | |
518 | scandir() [Added in POSIX.1-2008] | |
519 | scanf() | |
520 | seekdir() | |
521 | semop() | |
522 | setgrent() | |
523 | sethostent() | |
524 | setnetent() | |
525 | setprotoent() | |
526 | setpwent() | |
527 | setservent() | |
528 | setutxent() | |
529 | sigpause() [Added in POSIX.1-2008] | |
530 | stat() | |
531 | strerror() | |
532 | strerror_r() | |
533 | strftime() | |
534 | symlink() | |
535 | symlinkat() [Added in POSIX.1-2008] | |
536 | sync() | |
537 | syslog() | |
538 | tmpfile() | |
539 | tmpnam() | |
540 | ttyname() | |
541 | ttyname_r() | |
542 | tzset() | |
543 | ungetc() | |
544 | ungetwc() | |
545 | unlink() | |
546 | unlinkat() [Added in POSIX.1-2008] | |
547 | utime() [Added in POSIX.1-2008] | |
548 | utimensat() [Added in POSIX.1-2008] | |
549 | utimes() [Added in POSIX.1-2008] | |
550 | vdprintf() [Added in POSIX.1-2008] | |
551 | vfprintf() | |
552 | vfwprintf() | |
553 | vprintf() | |
554 | vwprintf() | |
555 | wcsftime() | |
556 | wordexp() | |
557 | wprintf() | |
558 | wscanf() | |
b8302363 | 559 | .EE |
ffe8c4ae | 560 | .in |
a721e8b2 | 561 | .PP |
ffe8c4ae MK |
562 | An implementation may also mark other functions |
563 | not specified in the standard as cancellation points. | |
564 | In particular, an implementation is likely to mark | |
c8f2dd47 | 565 | any nonstandard function that may block as a cancellation point. |
ffe8c4ae MK |
566 | (This includes most functions that can touch files.) |
567 | .\" So, scanning "cancellation point" comments in the glibc 2.8 header | |
c8f2dd47 | 568 | .\" files, it looks as though at least the following nonstandard |
ffe8c4ae MK |
569 | .\" functions are cancellation points: |
570 | .\" endnetgrent | |
571 | .\" endspent | |
572 | .\" epoll_pwait | |
573 | .\" epoll_wait | |
574 | .\" fcloseall | |
575 | .\" fdopendir | |
576 | .\" fflush_unlocked | |
577 | .\" fgetc_unlocked | |
578 | .\" fgetgrent | |
579 | .\" fgetgrent_r | |
580 | .\" fgetpwent | |
581 | .\" fgetpwent_r | |
582 | .\" fgets_unlocked | |
583 | .\" fgetspent | |
584 | .\" fgetspent_r | |
585 | .\" fgetwc_unlocked | |
586 | .\" fgetws_unlocked | |
587 | .\" fputc_unlocked | |
588 | .\" fputs_unlocked | |
589 | .\" fputwc_unlocked | |
590 | .\" fputws_unlocked | |
591 | .\" fread_unlocked | |
592 | .\" fwrite_unlocked | |
593 | .\" gai_suspend | |
594 | .\" getaddrinfo_a | |
595 | .\" getdate_r | |
596 | .\" getgrent_r | |
597 | .\" getgrouplist | |
598 | .\" gethostbyaddr_r | |
599 | .\" gethostbyname2 | |
600 | .\" gethostbyname2_r | |
601 | .\" gethostbyname_r | |
602 | .\" gethostent_r | |
603 | .\" getnetbyaddr_r | |
604 | .\" getnetbyname_r | |
605 | .\" getnetent_r | |
606 | .\" getnetgrent | |
607 | .\" getnetgrent_r | |
608 | .\" getprotobyname_r | |
609 | .\" getprotobynumber_r | |
610 | .\" getprotoent_r | |
611 | .\" getpw | |
612 | .\" getpwent_r | |
613 | .\" getservbyname_r | |
614 | .\" getservbyport_r | |
615 | .\" getservent_r | |
616 | .\" getspent | |
617 | .\" getspent_r | |
618 | .\" getspnam | |
619 | .\" getspnam_r | |
620 | .\" getutmp | |
621 | .\" getutmpx | |
622 | .\" getw | |
623 | .\" getwc_unlocked | |
624 | .\" getwchar_unlocked | |
625 | .\" initgroups | |
626 | .\" innetgr | |
627 | .\" mkostemp | |
628 | .\" mkostemp64 | |
629 | .\" mkstemp64 | |
630 | .\" ppoll | |
631 | .\" pthread_timedjoin_np | |
632 | .\" putgrent | |
633 | .\" putpwent | |
634 | .\" putspent | |
635 | .\" putw | |
636 | .\" putwc_unlocked | |
637 | .\" putwchar_unlocked | |
638 | .\" rcmd | |
639 | .\" rcmd_af | |
640 | .\" rexec | |
641 | .\" rexec_af | |
642 | .\" rresvport | |
643 | .\" rresvport_af | |
644 | .\" ruserok | |
645 | .\" ruserok_af | |
646 | .\" setnetgrent | |
647 | .\" setspent | |
648 | .\" sgetspent | |
649 | .\" sgetspent_r | |
650 | .\" updwtmpx | |
651 | .\" utmpxname | |
652 | .\" vfscanf | |
653 | .\" vfwscanf | |
654 | .\" vscanf | |
655 | .\" vsyslog | |
656 | .\" vwscanf | |
73d8cece | 657 | .SS Compiling on Linux |
3616b7c0 | 658 | On Linux, programs that use the Pthreads API should be compiled using |
4d9b6984 | 659 | .IR "cc \-pthread" . |
73d8cece | 660 | .SS Linux implementations of POSIX threads |
3616b7c0 MK |
661 | Over time, two threading implementations have been provided by |
662 | the GNU C library on Linux: | |
ffe649e9 | 663 | .TP |
a5e0a0e4 | 664 | .B LinuxThreads |
9bc64d3e MK |
665 | This is the original Pthreads implementation. |
666 | Since glibc 2.4, this implementation is no longer supported. | |
ffe649e9 MK |
667 | .TP |
668 | .BR NPTL " (Native POSIX Threads Library)" | |
3616b7c0 MK |
669 | This is the modern Pthreads implementation. |
670 | By comparison with LinuxThreads, NPTL provides closer conformance to | |
23a6e651 | 671 | the requirements of the POSIX.1 specification and better performance |
3616b7c0 | 672 | when creating large numbers of threads. |
9bc64d3e MK |
673 | NPTL is available since glibc 2.3.2, |
674 | and requires features that are present in the Linux 2.6 kernel. | |
3616b7c0 MK |
675 | .PP |
676 | Both of these are so-called 1:1 implementations, meaning that each | |
677 | thread maps to a kernel scheduling entity. | |
3616b7c0 MK |
678 | Both threading implementations employ the Linux |
679 | .BR clone (2) | |
680 | system call. | |
d9bfdb9c | 681 | In NPTL, thread synchronization primitives (mutexes, |
d88487cc | 682 | thread joining, and so on) are implemented using the Linux |
3616b7c0 MK |
683 | .BR futex (2) |
684 | system call. | |
3616b7c0 MK |
685 | .SS LinuxThreads |
686 | The notable features of this implementation are the following: | |
687 | .IP \- 3 | |
c13182ef | 688 | In addition to the main (initial) thread, |
23a6e651 | 689 | and the threads that the program creates using |
63f6a20a | 690 | .BR pthread_create (3), |
3616b7c0 MK |
691 | the implementation creates a "manager" thread. |
692 | This thread handles thread creation and termination. | |
693 | (Problems can result if this thread is inadvertently killed.) | |
694 | .IP \- 3 | |
695 | Signals are used internally by the implementation. | |
8bfd40a9 MK |
696 | On Linux 2.2 and later, the first three real-time signals are used |
697 | (see also | |
698 | .BR signal (7)). | |
8bd58774 MK |
699 | On older Linux kernels, |
700 | .B SIGUSR1 | |
701 | and | |
702 | .B SIGUSR2 | |
703 | are used. | |
23a6e651 | 704 | Applications must avoid the use of whichever set of signals is |
3616b7c0 MK |
705 | employed by the implementation. |
706 | .IP \- 3 | |
707 | Threads do not share process IDs. | |
708 | (In effect, LinuxThreads threads are implemented as processes which share | |
709 | more information than usual, but which do not share a common process ID.) | |
710 | LinuxThreads threads (including the manager thread) | |
711 | are visible as separate processes using | |
712 | .BR ps (1). | |
713 | .PP | |
714 | The LinuxThreads implementation deviates from the POSIX.1 | |
715 | specification in a number of ways, including the following: | |
716 | .IP \- 3 | |
717 | Calls to | |
718 | .BR getpid (2) | |
719 | return a different value in each thread. | |
720 | .IP \- 3 | |
23a6e651 | 721 | Calls to |
3616b7c0 MK |
722 | .BR getppid (2) |
723 | in threads other than the main thread return the process ID of the | |
724 | manager thread; instead | |
725 | .BR getppid (2) | |
726 | in these threads should return the same value as | |
727 | .BR getppid (2) | |
728 | in the main thread. | |
729 | .IP \- 3 | |
730 | When one thread creates a new child process using | |
731 | .BR fork (2), | |
732 | any thread should be able to | |
733 | .BR wait (2) | |
734 | on the child. | |
d1a2a5de | 735 | However, the implementation allows only the thread that |
3616b7c0 MK |
736 | created the child to |
737 | .BR wait (2) | |
738 | on it. | |
739 | .IP \- 3 | |
740 | When a thread calls | |
741 | .BR execve (2), | |
742 | all other threads are terminated (as required by POSIX.1). | |
743 | However, the resulting process has the same PID as the thread that called | |
744 | .BR execve (2): | |
745 | it should have the same PID as the main thread. | |
746 | .IP \- 3 | |
747 | Threads do not share user and group IDs. | |
880f5b4b | 748 | This can cause complications with set-user-ID programs and |
3616b7c0 MK |
749 | can cause failures in Pthreads functions if an application |
750 | changes its credentials using | |
751 | .BR seteuid (2) | |
752 | or similar. | |
753 | .IP \- 3 | |
754 | Threads do not share a common session ID and process group ID. | |
755 | .IP \- 3 | |
756 | Threads do not share record locks created using | |
757 | .BR fcntl (2). | |
758 | .IP \- 3 | |
759 | The information returned by | |
760 | .BR times (2) | |
761 | and | |
762 | .BR getrusage (2) | |
763 | is per-thread rather than process-wide. | |
764 | .IP \- 3 | |
765 | Threads do not share semaphore undo values (see | |
766 | .BR semop (2)). | |
767 | .IP \- 3 | |
768 | Threads do not share interval timers. | |
769 | .IP \- 3 | |
770 | Threads do not share a common nice value. | |
771 | .IP \- 3 | |
772 | POSIX.1 distinguishes the notions of signals that are directed | |
a7e7c7fc | 773 | to the process as a whole and signals that are directed to individual |
3616b7c0 MK |
774 | threads. |
775 | According to POSIX.1, a process-directed signal (sent using | |
776 | .BR kill (2), | |
777 | for example) should be handled by a single, | |
778 | arbitrarily selected thread within the process. | |
779 | LinuxThreads does not support the notion of process-directed signals: | |
33a0ccb2 | 780 | signals may be sent only to specific threads. |
3616b7c0 | 781 | .IP \- 3 |
23a6e651 MK |
782 | Threads have distinct alternate signal stack settings. |
783 | However, a new thread's alternate signal stack settings | |
61f4934a | 784 | are copied from the thread that created it, so that |
23a6e651 MK |
785 | the threads initially share an alternate signal stack. |
786 | (A new thread should start with no alternate signal stack defined. | |
787 | If two threads handle signals on their shared alternate signal | |
788 | stack at the same time, unpredictable program failures are | |
789 | likely to occur.) | |
3616b7c0 MK |
790 | .SS NPTL |
791 | With NPTL, all of the threads in a process are placed | |
792 | in the same thread group; | |