| 1 |
.\" Copyright 2005, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pthreads 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pthreads \- POSIX threads |
| 9 |
.SH DESCRIPTION |
| 10 |
POSIX.1 specifies a set of interfaces (functions, header files) for |
| 11 |
threaded programming commonly known as POSIX threads, or Pthreads. |
| 12 |
A single process can contain multiple threads, |
| 13 |
all of which are executing the same program. |
| 14 |
These threads share the same global memory (data and heap segments), |
| 15 |
but each thread has its own stack (automatic variables). |
| 16 |
.P |
| 17 |
POSIX.1 also requires that threads share a range of other attributes |
| 18 |
(i.e., these attributes are process-wide rather than per-thread): |
| 19 |
.IP \[bu] 3 |
| 20 |
process ID |
| 21 |
.IP \[bu] |
| 22 |
parent process ID |
| 23 |
.IP \[bu] |
| 24 |
process group ID and session ID |
| 25 |
.IP \[bu] |
| 26 |
controlling terminal |
| 27 |
.IP \[bu] |
| 28 |
user and group IDs |
| 29 |
.IP \[bu] |
| 30 |
open file descriptors |
| 31 |
.IP \[bu] |
| 32 |
record locks (see |
| 33 |
.BR fcntl (2)) |
| 34 |
.IP \[bu] |
| 35 |
signal dispositions |
| 36 |
.IP \[bu] |
| 37 |
file mode creation mask |
| 38 |
.RB ( umask (2)) |
| 39 |
.IP \[bu] |
| 40 |
current directory |
| 41 |
.RB ( chdir (2)) |
| 42 |
and |
| 43 |
root directory |
| 44 |
.RB ( chroot (2)) |
| 45 |
.IP \[bu] |
| 46 |
interval timers |
| 47 |
.RB ( setitimer (2)) |
| 48 |
and POSIX timers |
| 49 |
.RB ( timer_create (2)) |
| 50 |
.IP \[bu] |
| 51 |
nice value |
| 52 |
.RB ( setpriority (2)) |
| 53 |
.IP \[bu] |
| 54 |
resource limits |
| 55 |
.RB ( setrlimit (2)) |
| 56 |
.IP \[bu] |
| 57 |
measurements of the consumption of CPU time |
| 58 |
.RB ( times (2)) |
| 59 |
and resources |
| 60 |
.RB ( getrusage (2)) |
| 61 |
.P |
| 62 |
As well as the stack, POSIX.1 specifies that various other |
| 63 |
attributes are distinct for each thread, including: |
| 64 |
.IP \[bu] 3 |
| 65 |
thread ID (the |
| 66 |
.I pthread_t |
| 67 |
data type) |
| 68 |
.IP \[bu] |
| 69 |
signal mask |
| 70 |
.RB ( pthread_sigmask (3)) |
| 71 |
.IP \[bu] |
| 72 |
the |
| 73 |
.I errno |
| 74 |
variable |
| 75 |
.IP \[bu] |
| 76 |
alternate signal stack |
| 77 |
.RB ( sigaltstack (2)) |
| 78 |
.IP \[bu] |
| 79 |
real-time scheduling policy and priority |
| 80 |
.RB ( sched (7)) |
| 81 |
.P |
| 82 |
The following Linux-specific features are also per-thread: |
| 83 |
.IP \[bu] 3 |
| 84 |
capabilities (see |
| 85 |
.BR capabilities (7)) |
| 86 |
.IP \[bu] |
| 87 |
CPU affinity |
| 88 |
.RB ( sched_setaffinity (2)) |
| 89 |
.SS Pthreads function return values |
| 90 |
Most pthreads functions return 0 on success, and an error number on failure. |
| 91 |
The error numbers that can be returned have the same meaning as |
| 92 |
the error numbers returned in |
| 93 |
.I errno |
| 94 |
by conventional system calls and C library functions. |
| 95 |
Note that the pthreads functions do not set |
| 96 |
.IR errno . |
| 97 |
For each of the pthreads functions that can return an error, |
| 98 |
POSIX.1-2001 specifies that the function can never fail with the error |
| 99 |
.BR EINTR . |
| 100 |
.SS Thread IDs |
| 101 |
Each of the threads in a process has a unique thread identifier |
| 102 |
(stored in the type |
| 103 |
.IR pthread_t ). |
| 104 |
This identifier is returned to the caller of |
| 105 |
.BR pthread_create (3), |
| 106 |
and a thread can obtain its own thread identifier using |
| 107 |
.BR pthread_self (3). |
| 108 |
.P |
| 109 |
Thread IDs are guaranteed to be unique only within a process. |
| 110 |
(In all pthreads functions that accept a thread ID as an argument, |
| 111 |
that ID by definition refers to a thread in |
| 112 |
the same process as the caller.) |
| 113 |
.P |
| 114 |
The system may reuse a thread ID after a terminated thread has been joined, |
| 115 |
or a detached thread has terminated. |
| 116 |
POSIX says: "If an application attempts to use a thread ID whose |
| 117 |
lifetime has ended, the behavior is undefined." |
| 118 |
.SS Thread-safe functions |
| 119 |
A thread-safe function is one that can be safely |
| 120 |
(i.e., it will deliver the same results regardless of whether it is) |
| 121 |
called from multiple threads at the same time. |
| 122 |
.P |
| 123 |
POSIX.1-2001 and POSIX.1-2008 require that all functions specified |
| 124 |
in the standard shall be thread-safe, |
| 125 |
except for the following functions: |
| 126 |
.P |
| 127 |
.in +4n |
| 128 |
.EX |
| 129 |
asctime() |
| 130 |
basename() |
| 131 |
catgets() |
| 132 |
crypt() |
| 133 |
ctermid() if passed a non-NULL argument |
| 134 |
ctime() |
| 135 |
dbm_clearerr() |
| 136 |
dbm_close() |
| 137 |
dbm_delete() |
| 138 |
dbm_error() |
| 139 |
dbm_fetch() |
| 140 |
dbm_firstkey() |
| 141 |
dbm_nextkey() |
| 142 |
dbm_open() |
| 143 |
dbm_store() |
| 144 |
dirname() |
| 145 |
dlerror() |
| 146 |
drand48() |
| 147 |
ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
| 148 |
encrypt() |
| 149 |
endgrent() |
| 150 |
endpwent() |
| 151 |
endutxent() |
| 152 |
fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
| 153 |
ftw() |
| 154 |
gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
| 155 |
getc_unlocked() |
| 156 |
getchar_unlocked() |
| 157 |
getdate() |
| 158 |
getenv() |
| 159 |
getgrent() |
| 160 |
getgrgid() |
| 161 |
getgrnam() |
| 162 |
gethostbyaddr() [POSIX.1-2001 only (function removed in |
| 163 |
POSIX.1-2008)] |
| 164 |
gethostbyname() [POSIX.1-2001 only (function removed in |
| 165 |
POSIX.1-2008)] |
| 166 |
gethostent() |
| 167 |
getlogin() |
| 168 |
getnetbyaddr() |
| 169 |
getnetbyname() |
| 170 |
getnetent() |
| 171 |
getopt() |
| 172 |
getprotobyname() |
| 173 |
getprotobynumber() |
| 174 |
getprotoent() |
| 175 |
getpwent() |
| 176 |
getpwnam() |
| 177 |
getpwuid() |
| 178 |
getservbyname() |
| 179 |
getservbyport() |
| 180 |
getservent() |
| 181 |
getutxent() |
| 182 |
getutxid() |
| 183 |
getutxline() |
| 184 |
gmtime() |
| 185 |
hcreate() |
| 186 |
hdestroy() |
| 187 |
hsearch() |
| 188 |
inet_ntoa() |
| 189 |
l64a() |
| 190 |
lgamma() |
| 191 |
lgammaf() |
| 192 |
lgammal() |
| 193 |
localeconv() |
| 194 |
localtime() |
| 195 |
lrand48() |
| 196 |
mrand48() |
| 197 |
nftw() |
| 198 |
nl_langinfo() |
| 199 |
ptsname() |
| 200 |
putc_unlocked() |
| 201 |
putchar_unlocked() |
| 202 |
putenv() |
| 203 |
pututxline() |
| 204 |
rand() |
| 205 |
readdir() |
| 206 |
setenv() |
| 207 |
setgrent() |
| 208 |
setkey() |
| 209 |
setpwent() |
| 210 |
setutxent() |
| 211 |
strerror() |
| 212 |
strsignal() [Added in POSIX.1-2008] |
| 213 |
strtok() |
| 214 |
system() [Added in POSIX.1-2008] |
| 215 |
tmpnam() if passed a non-NULL argument |
| 216 |
ttyname() |
| 217 |
unsetenv() |
| 218 |
wcrtomb() if its final argument is NULL |
| 219 |
wcsrtombs() if its final argument is NULL |
| 220 |
wcstombs() |
| 221 |
wctomb() |
| 222 |
.EE |
| 223 |
.in |
| 224 |
.SS Async-cancel-safe functions |
| 225 |
An async-cancel-safe function is one that can be safely called |
| 226 |
in an application where asynchronous cancelability is enabled (see |
| 227 |
.BR pthread_setcancelstate (3)). |
| 228 |
.P |
| 229 |
Only the following functions are required to be async-cancel-safe by |
| 230 |
POSIX.1-2001 and POSIX.1-2008: |
| 231 |
.P |
| 232 |
.in +4n |
| 233 |
.EX |
| 234 |
pthread_cancel() |
| 235 |
pthread_setcancelstate() |
| 236 |
pthread_setcanceltype() |
| 237 |
.EE |
| 238 |
.in |
| 239 |
.SS Cancelation points |
| 240 |
POSIX.1 specifies that certain functions must, |
| 241 |
and certain other functions may, be cancelation points. |
| 242 |
If a thread is cancelable, its cancelability type is deferred, |
| 243 |
and a cancelation request is pending for the thread, |
| 244 |
then the thread is canceled when it calls a function |
| 245 |
that is a cancelation point. |
| 246 |
.P |
| 247 |
The following functions are required to be cancelation points by |
| 248 |
POSIX.1-2001 and/or POSIX.1-2008: |
| 249 |
.P |
| 250 |
.\" FIXME |
| 251 |
.\" Document the list of all functions that are cancelation points in glibc |
| 252 |
.in +4n |
| 253 |
.EX |
| 254 |
accept() |
| 255 |
aio_suspend() |
| 256 |
clock_nanosleep() |
| 257 |
close() |
| 258 |
connect() |
| 259 |
creat() |
| 260 |
fcntl() F_SETLKW |
| 261 |
fdatasync() |
| 262 |
fsync() |
| 263 |
getmsg() |
| 264 |
getpmsg() |
| 265 |
lockf() F_LOCK |
| 266 |
mq_receive() |
| 267 |
mq_send() |
| 268 |
mq_timedreceive() |
| 269 |
mq_timedsend() |
| 270 |
msgrcv() |
| 271 |
msgsnd() |
| 272 |
msync() |
| 273 |
nanosleep() |
| 274 |
open() |
| 275 |
openat() [Added in POSIX.1-2008] |
| 276 |
pause() |
| 277 |
poll() |
| 278 |
pread() |
| 279 |
pselect() |
| 280 |
pthread_cond_timedwait() |
| 281 |
pthread_cond_wait() |
| 282 |
pthread_join() |
| 283 |
pthread_testcancel() |
| 284 |
putmsg() |
| 285 |
putpmsg() |
| 286 |
pwrite() |
| 287 |
read() |
| 288 |
readv() |
| 289 |
recv() |
| 290 |
recvfrom() |
| 291 |
recvmsg() |
| 292 |
select() |
| 293 |
sem_timedwait() |
| 294 |
sem_wait() |
| 295 |
send() |
| 296 |
sendmsg() |
| 297 |
sendto() |
| 298 |
sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)] |
| 299 |
sigsuspend() |
| 300 |
sigtimedwait() |
| 301 |
sigwait() |
| 302 |
sigwaitinfo() |
| 303 |
sleep() |
| 304 |
system() |
| 305 |
tcdrain() |
| 306 |
usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
| 307 |
wait() |
| 308 |
waitid() |
| 309 |
waitpid() |
| 310 |
write() |
| 311 |
writev() |
| 312 |
.EE |
| 313 |
.in |
| 314 |
.P |
| 315 |
The following functions may be cancelation points according to |
| 316 |
POSIX.1-2001 and/or POSIX.1-2008: |
| 317 |
.P |
| 318 |
.in +4n |
| 319 |
.EX |
| 320 |
access() |
| 321 |
asctime() |
| 322 |
asctime_r() |
| 323 |
catclose() |
| 324 |
catgets() |
| 325 |
catopen() |
| 326 |
chmod() [Added in POSIX.1-2008] |
| 327 |
chown() [Added in POSIX.1-2008] |
| 328 |
closedir() |
| 329 |
closelog() |
| 330 |
ctermid() |
| 331 |
ctime() |
| 332 |
ctime_r() |
| 333 |
dbm_close() |
| 334 |
dbm_delete() |
| 335 |
dbm_fetch() |
| 336 |
dbm_nextkey() |
| 337 |
dbm_open() |
| 338 |
dbm_store() |
| 339 |
dlclose() |
| 340 |
dlopen() |
| 341 |
dprintf() [Added in POSIX.1-2008] |
| 342 |
endgrent() |
| 343 |
endhostent() |
| 344 |
endnetent() |
| 345 |
endprotoent() |
| 346 |
endpwent() |
| 347 |
endservent() |
| 348 |
endutxent() |
| 349 |
faccessat() [Added in POSIX.1-2008] |
| 350 |
fchmod() [Added in POSIX.1-2008] |
| 351 |
fchmodat() [Added in POSIX.1-2008] |
| 352 |
fchown() [Added in POSIX.1-2008] |
| 353 |
fchownat() [Added in POSIX.1-2008] |
| 354 |
fclose() |
| 355 |
fcntl() (for any value of cmd argument) |
| 356 |
fflush() |
| 357 |
fgetc() |
| 358 |
fgetpos() |
| 359 |
fgets() |
| 360 |
fgetwc() |
| 361 |
fgetws() |
| 362 |
fmtmsg() |
| 363 |
fopen() |
| 364 |
fpathconf() |
| 365 |
fprintf() |
| 366 |
fputc() |
| 367 |
fputs() |
| 368 |
fputwc() |
| 369 |
fputws() |
| 370 |
fread() |
| 371 |
freopen() |
| 372 |
fscanf() |
| 373 |
fseek() |
| 374 |
fseeko() |
| 375 |
fsetpos() |
| 376 |
fstat() |
| 377 |
fstatat() [Added in POSIX.1-2008] |
| 378 |
ftell() |
| 379 |
ftello() |
| 380 |
ftw() |
| 381 |
futimens() [Added in POSIX.1-2008] |
| 382 |
fwprintf() |
| 383 |
fwrite() |
| 384 |
fwscanf() |
| 385 |
getaddrinfo() |
| 386 |
getc() |
| 387 |
getc_unlocked() |
| 388 |
getchar() |
| 389 |
getchar_unlocked() |
| 390 |
getcwd() |
| 391 |
getdate() |
| 392 |
getdelim() [Added in POSIX.1-2008] |
| 393 |
getgrent() |
| 394 |
getgrgid() |
| 395 |
getgrgid_r() |
| 396 |
getgrnam() |
| 397 |
getgrnam_r() |
| 398 |
gethostbyaddr() [POSIX.1-2001 only (function removed in |
| 399 |
POSIX.1-2008)] |
| 400 |
gethostbyname() [POSIX.1-2001 only (function removed in |
| 401 |
POSIX.1-2008)] |
| 402 |
gethostent() |
| 403 |
gethostid() |
| 404 |
gethostname() |
| 405 |
getline() [Added in POSIX.1-2008] |
| 406 |
getlogin() |
| 407 |
getlogin_r() |
| 408 |
getnameinfo() |
| 409 |
getnetbyaddr() |
| 410 |
getnetbyname() |
| 411 |
getnetent() |
| 412 |
getopt() (if opterr is nonzero) |
| 413 |
getprotobyname() |
| 414 |
getprotobynumber() |
| 415 |
getprotoent() |
| 416 |
getpwent() |
| 417 |
getpwnam() |
| 418 |
getpwnam_r() |
| 419 |
getpwuid() |
| 420 |
getpwuid_r() |
| 421 |
gets() |
| 422 |
getservbyname() |
| 423 |
getservbyport() |
| 424 |
getservent() |
| 425 |
getutxent() |
| 426 |
getutxid() |
| 427 |
getutxline() |
| 428 |
getwc() |
| 429 |
getwchar() |
| 430 |
getwd() [POSIX.1-2001 only (function removed in POSIX.1-2008)] |
| 431 |
glob() |
| 432 |
iconv_close() |
| 433 |
iconv_open() |
| 434 |
ioctl() |
| 435 |
link() |
| 436 |
linkat() [Added in POSIX.1-2008] |
| 437 |
lio_listio() [Added in POSIX.1-2008] |
| 438 |
localtime() |
| 439 |
localtime_r() |
| 440 |
lockf() [Added in POSIX.1-2008] |
| 441 |
lseek() |
| 442 |
lstat() |
| 443 |
mkdir() [Added in POSIX.1-2008] |
| 444 |
mkdirat() [Added in POSIX.1-2008] |
| 445 |
mkdtemp() [Added in POSIX.1-2008] |
| 446 |
mkfifo() [Added in POSIX.1-2008] |
| 447 |
mkfifoat() [Added in POSIX.1-2008] |
| 448 |
mknod() [Added in POSIX.1-2008] |
| 449 |
mknodat() [Added in POSIX.1-2008] |
| 450 |
mkstemp() |
| 451 |
mktime() |
| 452 |
nftw() |
| 453 |
opendir() |
| 454 |
openlog() |
| 455 |
pathconf() |
| 456 |
pclose() |
| 457 |
perror() |
| 458 |
popen() |
| 459 |
posix_fadvise() |
| 460 |
posix_fallocate() |
| 461 |
posix_madvise() |
| 462 |
posix_openpt() |
| 463 |
posix_spawn() |
| 464 |
posix_spawnp() |
| 465 |
posix_trace_clear() |
| 466 |
posix_trace_close() |
| 467 |
posix_trace_create() |
| 468 |
posix_trace_create_withlog() |
| 469 |
posix_trace_eventtypelist_getnext_id() |
| 470 |
posix_trace_eventtypelist_rewind() |
| 471 |
posix_trace_flush() |
| 472 |
posix_trace_get_attr() |
| 473 |
posix_trace_get_filter() |
| 474 |
posix_trace_get_status() |
| 475 |
posix_trace_getnext_event() |
| 476 |
posix_trace_open() |
| 477 |
posix_trace_rewind() |
| 478 |
posix_trace_set_filter() |
| 479 |
posix_trace_shutdown() |
| 480 |
posix_trace_timedgetnext_event() |
| 481 |
posix_typed_mem_open() |
| 482 |
printf() |
| 483 |
psiginfo() [Added in POSIX.1-2008] |
| 484 |
psignal() [Added in POSIX.1-2008] |
| 485 |
pthread_rwlock_rdlock() |
| 486 |
pthread_rwlock_timedrdlock() |
| 487 |
pthread_rwlock_timedwrlock() |
| 488 |
pthread_rwlock_wrlock() |
| 489 |
putc() |
| 490 |
putc_unlocked() |
| 491 |
putchar() |
| 492 |
putchar_unlocked() |
| 493 |
puts() |
| 494 |
pututxline() |
| 495 |
putwc() |
| 496 |
putwchar() |
| 497 |
readdir() |
| 498 |
readdir_r() |
| 499 |
readlink() [Added in POSIX.1-2008] |
| 500 |
readlinkat() [Added in POSIX.1-2008] |
| 501 |
remove() |
| 502 |
rename() |
| 503 |
renameat() [Added in POSIX.1-2008] |
| 504 |
rewind() |
| 505 |
rewinddir() |
| 506 |
scandir() [Added in POSIX.1-2008] |
| 507 |
scanf() |
| 508 |
seekdir() |
| 509 |
semop() |
| 510 |
setgrent() |
| 511 |
sethostent() |
| 512 |
setnetent() |
| 513 |
setprotoent() |
| 514 |
setpwent() |
| 515 |
setservent() |
| 516 |
setutxent() |
| 517 |
sigpause() [Added in POSIX.1-2008] |
| 518 |
stat() |
| 519 |
strerror() |
| 520 |
strerror_r() |
| 521 |
strftime() |
| 522 |
symlink() |
| 523 |
symlinkat() [Added in POSIX.1-2008] |
| 524 |
sync() |
| 525 |
syslog() |
| 526 |
tmpfile() |
| 527 |
tmpnam() |
| 528 |
ttyname() |
| 529 |
ttyname_r() |
| 530 |
tzset() |
| 531 |
ungetc() |
| 532 |
ungetwc() |
| 533 |
unlink() |
| 534 |
unlinkat() [Added in POSIX.1-2008] |
| 535 |
utime() [Added in POSIX.1-2008] |
| 536 |
utimensat() [Added in POSIX.1-2008] |
| 537 |
utimes() [Added in POSIX.1-2008] |
| 538 |
vdprintf() [Added in POSIX.1-2008] |
| 539 |
vfprintf() |
| 540 |
vfwprintf() |
| 541 |
vprintf() |
| 542 |
vwprintf() |
| 543 |
wcsftime() |
| 544 |
wordexp() |
| 545 |
wprintf() |
| 546 |
wscanf() |
| 547 |
.EE |
| 548 |
.in |
| 549 |
.P |
| 550 |
An implementation may also mark other functions |
| 551 |
not specified in the standard as cancelation points. |
| 552 |
In particular, an implementation is likely to mark |
| 553 |
any nonstandard function that may block as a cancelation point. |
| 554 |
(This includes most functions that can touch files.) |
| 555 |
.P |
| 556 |
It should be noted that even if an application is not using |
| 557 |
asynchronous cancelation, that calling a function from the above list |
| 558 |
from an asynchronous signal handler may cause the equivalent of |
| 559 |
asynchronous cancelation. |
| 560 |
The underlying user code may not expect |
| 561 |
asynchronous cancelation and the state of the user data may become |
| 562 |
inconsistent. |
| 563 |
Therefore signals should be used with caution when |
| 564 |
entering a region of deferred cancelation. |
| 565 |
.\" So, scanning "cancelation point" comments in the glibc 2.8 header |
| 566 |
.\" files, it looks as though at least the following nonstandard |
| 567 |
.\" functions are cancelation points: |
| 568 |
.\" endnetgrent |
| 569 |
.\" endspent |
| 570 |
.\" epoll_pwait |
| 571 |
.\" epoll_wait |
| 572 |
.\" fcloseall |
| 573 |
.\" fdopendir |
| 574 |
.\" fflush_unlocked |
| 575 |
.\" fgetc_unlocked |
| 576 |
.\" fgetgrent |
| 577 |
.\" fgetgrent_r |
| 578 |
.\" fgetpwent |
| 579 |
.\" fgetpwent_r |
| 580 |
.\" fgets_unlocked |
| 581 |
.\" fgetspent |
| 582 |
.\" fgetspent_r |
| 583 |
.\" fgetwc_unlocked |
| 584 |
.\" fgetws_unlocked |
| 585 |
.\" fputc_unlocked |
| 586 |
.\" fputs_unlocked |
| 587 |
.\" fputwc_unlocked |
| 588 |
.\" fputws_unlocked |
| 589 |
.\" fread_unlocked |
| 590 |
.\" fwrite_unlocked |
| 591 |
.\" gai_suspend |
| 592 |
.\" getaddrinfo_a |
| 593 |
.\" getdate_r |
| 594 |
.\" getgrent_r |
| 595 |
.\" getgrouplist |
| 596 |
.\" gethostbyaddr_r |
| 597 |
.\" gethostbyname2 |
| 598 |
.\" gethostbyname2_r |
| 599 |
.\" gethostbyname_r |
| 600 |
.\" gethostent_r |
| 601 |
.\" getnetbyaddr_r |
| 602 |
.\" getnetbyname_r |
| 603 |
.\" getnetent_r |
| 604 |
.\" getnetgrent |
| 605 |
.\" getnetgrent_r |
| 606 |
.\" getprotobyname_r |
| 607 |
.\" getprotobynumber_r |
| 608 |
.\" getprotoent_r |
| 609 |
.\" getpw |
| 610 |
.\" getpwent_r |
| 611 |
.\" getservbyname_r |
| 612 |
.\" getservbyport_r |
| 613 |
.\" getservent_r |
| 614 |
.\" getspent |
| 615 |
.\" getspent_r |
| 616 |
.\" getspnam |
| 617 |
.\" getspnam_r |
| 618 |
.\" getutmp |
| 619 |
.\" getutmpx |
| 620 |
.\" getw |
| 621 |
.\" getwc_unlocked |
| 622 |
.\" getwchar_unlocked |
| 623 |
.\" initgroups |
| 624 |
.\" innetgr |
| 625 |
.\" mkostemp |
| 626 |
.\" mkostemp64 |
| 627 |
.\" mkstemp64 |
| 628 |
.\" ppoll |
| 629 |
.\" pthread_timedjoin_np |
| 630 |
.\" putgrent |
| 631 |
.\" putpwent |
| 632 |
.\" putspent |
| 633 |
.\" putw |
| 634 |
.\" putwc_unlocked |
| 635 |
.\" putwchar_unlocked |
| 636 |
.\" rcmd |
| 637 |
.\" rcmd_af |
| 638 |
.\" rexec |
| 639 |
.\" rexec_af |
| 640 |
.\" rresvport |
| 641 |
.\" rresvport_af |
| 642 |
.\" ruserok |
| 643 |
.\" ruserok_af |
| 644 |
.\" setnetgrent |
| 645 |
.\" setspent |
| 646 |
.\" sgetspent |
| 647 |
.\" sgetspent_r |
| 648 |
.\" updwtmpx |
| 649 |
.\" utmpxname |
| 650 |
.\" vfscanf |
| 651 |
.\" vfwscanf |
| 652 |
.\" vscanf |
| 653 |
.\" vsyslog |
| 654 |
.\" vwscanf |
| 655 |
.SS Compiling on Linux |
| 656 |
On Linux, programs that use the Pthreads API should be compiled using |
| 657 |
.IR "cc \-pthread" . |
| 658 |
.SS Linux implementations of POSIX threads |
| 659 |
Over time, two threading implementations have been provided by |
| 660 |
the GNU C library on Linux: |
| 661 |
.TP |
| 662 |
.B LinuxThreads |
| 663 |
This is the original Pthreads implementation. |
| 664 |
Since glibc 2.4, this implementation is no longer supported. |
| 665 |
.TP |
| 666 |
.BR NPTL " (Native POSIX Threads Library)" |
| 667 |
This is the modern Pthreads implementation. |
| 668 |
By comparison with LinuxThreads, NPTL provides closer conformance to |
| 669 |
the requirements of the POSIX.1 specification and better performance |
| 670 |
when creating large numbers of threads. |
| 671 |
NPTL is available since glibc 2.3.2, |
| 672 |
and requires features that are present in the Linux 2.6 kernel. |
| 673 |
.P |
| 674 |
Both of these are so-called 1:1 implementations, meaning that each |
| 675 |
thread maps to a kernel scheduling entity. |
| 676 |
Both threading implementations employ the Linux |
| 677 |
.BR clone (2) |
| 678 |
system call. |
| 679 |
In NPTL, thread synchronization primitives (mutexes, |
| 680 |
thread joining, and so on) are implemented using the Linux |
| 681 |
.BR futex (2) |
| 682 |
system call. |
| 683 |
.SS LinuxThreads |
| 684 |
The notable features of this implementation are the following: |
| 685 |
.IP \[bu] 3 |
| 686 |
In addition to the main (initial) thread, |
| 687 |
and the threads that the program creates using |
| 688 |
.BR pthread_create (3), |
| 689 |
the implementation creates a "manager" thread. |
| 690 |
This thread handles thread creation and termination. |
| 691 |
(Problems can result if this thread is inadvertently killed.) |
| 692 |
.IP \[bu] |
| 693 |
Signals are used internally by the implementation. |
| 694 |
On Linux 2.2 and later, the first three real-time signals are used |
| 695 |
(see also |
| 696 |
.BR signal (7)). |
| 697 |
On older Linux kernels, |
| 698 |
.B SIGUSR1 |
| 699 |
and |
| 700 |
.B SIGUSR2 |
| 701 |
are used. |
| 702 |
Applications must avoid the use of whichever set of signals is |
| 703 |
employed by the implementation. |
| 704 |
.IP \[bu] |
| 705 |
Threads do not share process IDs. |
| 706 |
(In effect, LinuxThreads threads are implemented as processes which share |
| 707 |
more information than usual, but which do not share a common process ID.) |
| 708 |
LinuxThreads threads (including the manager thread) |
| 709 |
are visible as separate processes using |
| 710 |
.BR ps (1). |
| 711 |
.P |
| 712 |
The LinuxThreads implementation deviates from the POSIX.1 |
| 713 |
specification in a number of ways, including the following: |
| 714 |
.IP \[bu] 3 |
| 715 |
Calls to |
| 716 |
.BR getpid (2) |
| 717 |
return a different value in each thread. |
| 718 |
.IP \[bu] |
| 719 |
Calls to |
| 720 |
.BR getppid (2) |
| 721 |
in threads other than the main thread return the process ID of the |
| 722 |
manager thread; |
| 723 |
instead |
| 724 |
.BR getppid (2) |
| 725 |
in these threads should return the same value as |
| 726 |
.BR getppid (2) |
| 727 |
in the main thread. |
| 728 |
.IP \[bu] |
| 729 |
When one thread creates a new child process using |
| 730 |
.BR fork (2), |
| 731 |
any thread should be able to |
| 732 |
.BR wait (2) |
| 733 |
on the child. |
| 734 |
However, the implementation allows only the thread that |
| 735 |
created the child to |
| 736 |
.BR wait (2) |
| 737 |
on it. |
| 738 |
.IP \[bu] |
| 739 |
When a thread calls |
| 740 |
.BR execve (2), |
| 741 |
all other threads are terminated (as required by POSIX.1). |
| 742 |
However, the resulting process has the same PID as the thread that called |
| 743 |
.BR execve (2): |
| 744 |
it should have the same PID as the main thread. |
| 745 |
.IP \[bu] |
| 746 |
Threads do not share user and group IDs. |
| 747 |
This can cause complications with set-user-ID programs and |
| 748 |
can cause failures in Pthreads functions if an application |
| 749 |
changes its credentials using |
| 750 |
.BR seteuid (2) |
| 751 |
or similar. |
| 752 |
.IP \[bu] |
| 753 |
Threads do not share a common session ID and process group ID. |
| 754 |
.IP \[bu] |
| 755 |
Threads do not share record locks created using |
| 756 |
.BR fcntl (2). |
| 757 |
.IP \[bu] |
| 758 |
The information returned by |
| 759 |
.BR times (2) |
| 760 |
and |
| 761 |
.BR getrusage (2) |
| 762 |
is per-thread rather than process-wide. |
| 763 |
.IP \[bu] |
| 764 |
Threads do not share semaphore undo values (see |
| 765 |
.BR semop (2)). |
| 766 |
.IP \[bu] |
| 767 |
Threads do not share interval timers. |
| 768 |
.IP \[bu] |
| 769 |
Threads do not share a common nice value. |
| 770 |
.IP \[bu] |
| 771 |
POSIX.1 distinguishes the notions of signals that are directed |
| 772 |
to the process as a whole and signals that are directed to individual |
| 773 |
threads. |
| 774 |
According to POSIX.1, a process-directed signal (sent using |
| 775 |
.BR kill (2), |
| 776 |
for example) should be handled by a single, |
| 777 |
arbitrarily selected thread within the process. |
| 778 |
LinuxThreads does not support the notion of process-directed signals: |
| 779 |
signals may be sent only to specific threads. |
| 780 |
.IP \[bu] |
| 781 |
Threads have distinct alternate signal stack settings. |
| 782 |
However, a new thread's alternate signal stack settings |
| 783 |
are copied from the thread that created it, so that |
| 784 |
the threads initially share an alternate signal stack. |
| 785 |
(A new thread should start with no alternate signal stack defined. |
| 786 |
If two threads handle signals on their shared alternate signal |
| 787 |
stack at the same time, unpredictable program failures are |
| 788 |
likely to occur.) |
| 789 |
.SS NPTL |
| 790 |
With NPTL, all of the threads in a process are placed |
| 791 |
in the same thread group; |
| 792 |
all members of a thread group share the same PID. |
| 793 |
NPTL does not employ a manager thread. |
| 794 |
.P |
| 795 |
NPTL makes internal use of the first two real-time signals; |
| 796 |
these signals cannot be used in applications. |
| 797 |
See |
| 798 |
.BR nptl (7) |
| 799 |
for further details. |
| 800 |
.P |
| 801 |
NPTL still has at least one nonconformance with POSIX.1: |
| 802 |
.IP \[bu] 3 |
| 803 |
Threads do not share a common nice value. |
| 804 |
.\" FIXME . bug report filed for NPTL nice nonconformance |
| 805 |
.\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 |
| 806 |
.\" Sep 08: there is a patch by Denys Vlasenko to address this |
| 807 |
.\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" |
| 808 |
.\" Monitor this to see if it makes it into mainline. |
| 809 |
.P |
| 810 |
Some NPTL nonconformances occur only with older kernels: |
| 811 |
.IP \[bu] 3 |
| 812 |
The information returned by |
| 813 |
.BR times (2) |
| 814 |
and |
| 815 |
.BR getrusage (2) |
| 816 |
is per-thread rather than process-wide (fixed in Linux 2.6.9). |
| 817 |
.IP \[bu] |
| 818 |
Threads do not share resource limits (fixed in Linux 2.6.10). |
| 819 |
.IP \[bu] |
| 820 |
Threads do not share interval timers (fixed in Linux 2.6.12). |
| 821 |
.IP \[bu] |
| 822 |
Only the main thread is permitted to start a new session using |
| 823 |
.BR setsid (2) |
| 824 |
(fixed in Linux 2.6.16). |
| 825 |
.IP \[bu] |
| 826 |
Only the main thread is permitted to make the process into a |
| 827 |
process group leader using |
| 828 |
.BR setpgid (2) |
| 829 |
(fixed in Linux 2.6.16). |
| 830 |
.IP \[bu] |
| 831 |
Threads have distinct alternate signal stack settings. |
| 832 |
However, a new thread's alternate signal stack settings |
| 833 |
are copied from the thread that created it, so that |
| 834 |
the threads initially share an alternate signal stack |
| 835 |
(fixed in Linux 2.6.16). |
| 836 |
.P |
| 837 |
Note the following further points about the NPTL implementation: |
| 838 |
.IP \[bu] 3 |
| 839 |
If the stack size soft resource limit (see the description of |
| 840 |
.B RLIMIT_STACK |
| 841 |
in |
| 842 |
.BR setrlimit (2)) |
| 843 |
is set to a value other than |
| 844 |
.IR unlimited , |
| 845 |
then this value defines the default stack size for new threads. |
| 846 |
To be effective, this limit must be set before the program |
| 847 |
is executed, perhaps using the |
| 848 |
.I ulimit \-s |
| 849 |
shell built-in command |
| 850 |
.RI ( "limit stacksize" |
| 851 |
in the C shell). |
| 852 |
.SS Determining the threading implementation |
| 853 |
Since glibc 2.3.2, the |
| 854 |
.BR getconf (1) |
| 855 |
command can be used to determine |
| 856 |
the system's threading implementation, for example: |
| 857 |
.P |
| 858 |
.in +4n |
| 859 |
.EX |
| 860 |
bash$ getconf GNU_LIBPTHREAD_VERSION |
| 861 |
NPTL 2.3.4 |
| 862 |
.EE |
| 863 |
.in |
| 864 |
.P |
| 865 |
With older glibc versions, a command such as the following should |
| 866 |
be sufficient to determine the default threading implementation: |
| 867 |
.P |
| 868 |
.in +4n |
| 869 |
.EX |
| 870 |
bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \[rs] |
| 871 |
egrep \-i \[aq]threads|nptl\[aq] |
| 872 |
Native POSIX Threads Library by Ulrich Drepper et al |
| 873 |
.EE |
| 874 |
.in |
| 875 |
.SS Selecting the threading implementation: LD_ASSUME_KERNEL |
| 876 |
On systems with a glibc that supports both LinuxThreads and NPTL |
| 877 |
(i.e., glibc 2.3.*), the |
| 878 |
.B LD_ASSUME_KERNEL |
| 879 |
environment variable can be used to override |
| 880 |
the dynamic linker's default choice of threading implementation. |
| 881 |
This variable tells the dynamic linker to assume that it is |
| 882 |
running on top of a particular kernel version. |
| 883 |
By specifying a kernel version that does not |
| 884 |
provide the support required by NPTL, we can force the use |
| 885 |
of LinuxThreads. |
| 886 |
(The most likely reason for doing this is to run a |
| 887 |
(broken) application that depends on some nonconformant behavior |
| 888 |
in LinuxThreads.) |
| 889 |
For example: |
| 890 |
.P |
| 891 |
.in +4n |
| 892 |
.EX |
| 893 |
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \[rs] |
| 894 |
awk \[aq]{print $3}\[aq] ) | egrep \-i \[aq]threads|nptl\[aq] |
| 895 |
linuxthreads\-0.10 by Xavier Leroy |
| 896 |
.EE |
| 897 |
.in |
| 898 |
.SH SEE ALSO |
| 899 |
.ad l |
| 900 |
.nh |
| 901 |
.BR clone (2), |
| 902 |
.BR fork (2), |
| 903 |
.BR futex (2), |
| 904 |
.BR gettid (2), |
| 905 |
.BR proc (5), |
| 906 |
.BR attributes (7), |
| 907 |
.BR futex (7), |
| 908 |
.BR nptl (7), |
| 909 |
.BR sigevent (3type), |
| 910 |
.BR signal (7) |
| 911 |
.P |
| 912 |
Various Pthreads manual pages, for example: |
| 913 |
.BR pthread_atfork (3), |
| 914 |
.BR pthread_attr_init (3), |
| 915 |
.BR pthread_cancel (3), |
| 916 |
.BR pthread_cleanup_push (3), |
| 917 |
.BR pthread_cond_signal (3), |
| 918 |
.BR pthread_cond_wait (3), |
| 919 |
.BR pthread_create (3), |
| 920 |
.BR pthread_detach (3), |
| 921 |
.BR pthread_equal (3), |
| 922 |
.BR pthread_exit (3), |
| 923 |
.BR pthread_key_create (3), |
| 924 |
.BR pthread_kill (3), |
| 925 |
.BR pthread_mutex_lock (3), |
| 926 |
.BR pthread_mutex_unlock (3), |
| 927 |
.BR pthread_mutexattr_destroy (3), |
| 928 |
.BR pthread_mutexattr_init (3), |
| 929 |
.BR pthread_once (3), |
| 930 |
.BR pthread_spin_init (3), |
| 931 |
.BR pthread_spin_lock (3), |
| 932 |
.BR pthread_rwlockattr_setkind_np (3), |
| 933 |
.BR pthread_setcancelstate (3), |
| 934 |
.BR pthread_setcanceltype (3), |
| 935 |
.BR pthread_setspecific (3), |
| 936 |
.BR pthread_sigmask (3), |
| 937 |
.BR pthread_sigqueue (3), |
| 938 |
and |
| 939 |
.BR pthread_testcancel (3) |