1PTHREADS(7) Linux Programmer's Manual PTHREADS(7)
2
6 pthreads - POSIX threads
7
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 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 - process ID
20 - parent process ID
22 - process group ID and session ID
24 - controlling terminal
26 - user and group IDs
28 - open file descriptors
30 - record locks (see fcntl(2))
32 - signal dispositions
34 - file mode creation mask (umask(2))
36 - current directory (chdir(2)) and root directory (chroot(2))
38 - interval timers (setitimer(2)) and POSIX timers (timer_create(2))
40 - nice value (setpriority(2))
42 - resource limits (setrlimit(2))
44 - measurements of the consumption of CPU time (times(2)) and resources
46 (getrusage(2))
47 As well as the stack, POSIX.1 specifies that various other attributes
49 are distinct for each thread, including:
50 - thread ID (the pthread_t data type)
52 - signal mask (pthread_sigmask(3))
54 - the errno variable
56 - alternate signal stack (sigaltstack(2))
58 - real-time scheduling policy and priority (sched(7))
60 The following Linux-specific features are also per-thread:
62 - capabilities (see capabilities(7))
64 - CPU affinity (sched_setaffinity(2))
66 Pthreads function return values
68 Most pthreads functions return 0 on success, and an error number on
69 failure. The error numbers that can be returned have the same meaning
70 as the error numbers returned in errno by conventional system calls and
71 C library functions. Note that the pthreads functions do not set er‐
72 rno. For each of the pthreads functions that can return an error,
73 POSIX.1-2001 specifies that the function can never fail with the error
74 EINTR.
75 Thread IDs
77 Each of the threads in a process has a unique thread identifier (stored
78 in the type pthread_t). This identifier is returned to the caller of
79 pthread_create(3), and a thread can obtain its own thread identifier
80 using pthread_self(3).
81 Thread IDs are guaranteed to be unique only within a process. (In all
83 pthreads functions that accept a thread ID as an argument, that ID by
84 definition refers to a thread in the same process as the caller.)
85 The system may reuse a thread ID after a terminated thread has been
87 joined, or a detached thread has terminated. POSIX says: "If an appli‐
88 cation attempts to use a thread ID whose lifetime has ended, the behav‐
89 ior is undefined."
90 Thread-safe functions
92 A thread-safe function is one that can be safely (i.e., it will deliver
93 the same results regardless of whether it is) called from multiple
94 threads at the same time.
95 POSIX.1-2001 and POSIX.1-2008 require that all functions specified in
97 the standard shall be thread-safe, except for the following functions:
98 asctime()
100 basename()
101 catgets()
102 crypt()
103 ctermid() if passed a non-NULL argument
104 ctime()
105 dbm_clearerr()
106 dbm_close()
107 dbm_delete()
108 dbm_error()
109 dbm_fetch()
110 dbm_firstkey()
111 dbm_nextkey()
112 dbm_open()
113 dbm_store()
114 dirname()
115 dlerror()
116 drand48()
117 ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
118 encrypt()
119 endgrent()
120 endpwent()
121 endutxent()
122 fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
123 ftw()
124 gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
125 getc_unlocked()
126 getchar_unlocked()
127 getdate()
128 getenv()
129 getgrent()
130 getgrgid()
131 getgrnam()
132 gethostbyaddr() [POSIX.1-2001 only (function removed in
133 POSIX.1-2008)]
134 gethostbyname() [POSIX.1-2001 only (function removed in
135 POSIX.1-2008)]
136 gethostent()
137 getlogin()
138 getnetbyaddr()
139 getnetbyname()
140 getnetent()
141 getopt()
142 getprotobyname()
143 getprotobynumber()
144 getprotoent()
145 getpwent()
146 getpwnam()
147 getpwuid()
148 getservbyname()
149 getservbyport()
150 getservent()
151 getutxent()
152 getutxid()
153 getutxline()
154 gmtime()
155 hcreate()
156 hdestroy()
157 hsearch()
158 inet_ntoa()
159 l64a()
160 lgamma()
161 lgammaf()
162 lgammal()
163 localeconv()
164 localtime()
165 lrand48()
166 mrand48()
167 nftw()
168 nl_langinfo()
169 ptsname()
170 putc_unlocked()
171 putchar_unlocked()
172 putenv()
173 pututxline()
174 rand()
175 readdir()
176 setenv()
177 setgrent()
178 setkey()
179 setpwent()
180 setutxent()
181 strerror()
182 strsignal() [Added in POSIX.1-2008]
183 strtok()
184 system() [Added in POSIX.1-2008]
185 tmpnam() if passed a non-NULL argument
186 ttyname()
187 unsetenv()
188 wcrtomb() if its final argument is NULL
189 wcsrtombs() if its final argument is NULL
190 wcstombs()
191 wctomb()
192 Async-cancel-safe functions
194 An async-cancel-safe function is one that can be safely called in an
195 application where asynchronous cancelability is enabled (see
196 pthread_setcancelstate(3)).
197 Only the following functions are required to be async-cancel-safe by
199 POSIX.1-2001 and POSIX.1-2008:
200 pthread_cancel()
202 pthread_setcancelstate()
203 pthread_setcanceltype()
204 Cancellation points
206 POSIX.1 specifies that certain functions must, and certain other func‐
207 tions may, be cancellation points. If a thread is cancelable, its can‐
208 celability type is deferred, and a cancellation request is pending for
209 the thread, then the thread is canceled when it calls a function that
210 is a cancellation point.
211 The following functions are required to be cancellation points by
213 POSIX.1-2001 and/or POSIX.1-2008:
214 accept()
216 aio_suspend()
217 clock_nanosleep()
218 close()
219 connect()
220 creat()
221 fcntl() F_SETLKW
222 fdatasync()
223 fsync()
224 getmsg()
225 getpmsg()
226 lockf() F_LOCK
227 mq_receive()
228 mq_send()
229 mq_timedreceive()
230 mq_timedsend()
231 msgrcv()
232 msgsnd()
233 msync()
234 nanosleep()
235 open()
236 openat() [Added in POSIX.1-2008]
237 pause()
238 poll()
239 pread()
240 pselect()
241 pthread_cond_timedwait()
242 pthread_cond_wait()
243 pthread_join()
244 pthread_testcancel()
245 putmsg()
246 putpmsg()
247 pwrite()
248 read()
249 readv()
250 recv()
251 recvfrom()
252 recvmsg()
253 select()
254 sem_timedwait()
255 sem_wait()
256 send()
257 sendmsg()
258 sendto()
259 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
260 sigsuspend()
261 sigtimedwait()
262 sigwait()
263 sigwaitinfo()
264 sleep()
265 system()
266 tcdrain()
267 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
268 wait()
269 waitid()
270 waitpid()
271 write()
272 writev()
273 The following functions may be cancellation points according to
275 POSIX.1-2001 and/or POSIX.1-2008:
276 access()
278 asctime()
279 asctime_r()
280 catclose()
281 catgets()
282 catopen()
283 chmod() [Added in POSIX.1-2008]
284 chown() [Added in POSIX.1-2008]
285 closedir()
286 closelog()
287 ctermid()
288 ctime()
289 ctime_r()
290 dbm_close()
291 dbm_delete()
292 dbm_fetch()
293 dbm_nextkey()
294 dbm_open()
295 dbm_store()
296 dlclose()
297 dlopen()
298 dprintf() [Added in POSIX.1-2008]
299 endgrent()
300 endhostent()
301 endnetent()
302 endprotoent()
303 endpwent()
304 endservent()
305 endutxent()
306 faccessat() [Added in POSIX.1-2008]
307 fchmod() [Added in POSIX.1-2008]
308 fchmodat() [Added in POSIX.1-2008]
309 fchown() [Added in POSIX.1-2008]
310 fchownat() [Added in POSIX.1-2008]
311 fclose()
312 fcntl() (for any value of cmd argument)
313 fflush()
314 fgetc()
315 fgetpos()
316 fgets()
317 fgetwc()
318 fgetws()
319 fmtmsg()
320 fopen()
321 fpathconf()
322 fprintf()
323 fputc()
324 fputs()
325 fputwc()
326 fputws()
327 fread()
328 freopen()
329 fscanf()
330 fseek()
331 fseeko()
332 fsetpos()
333 fstat()
334 fstatat() [Added in POSIX.1-2008]
335 ftell()
336 ftello()
337 ftw()
338 futimens() [Added in POSIX.1-2008]
339 fwprintf()
340 fwrite()
341 fwscanf()
342 getaddrinfo()
343 getc()
344 getc_unlocked()
345 getchar()
346 getchar_unlocked()
347 getcwd()
348 getdate()
349 getdelim() [Added in POSIX.1-2008]
350 getgrent()
351 getgrgid()
352 getgrgid_r()
353 getgrnam()
354 getgrnam_r()
355 gethostbyaddr() [POSIX.1-2001 only (function removed in
356 POSIX.1-2008)]
357 gethostbyname() [POSIX.1-2001 only (function removed in
358 POSIX.1-2008)]
359 gethostent()
360 gethostid()
361 gethostname()
362 getline() [Added in POSIX.1-2008]
363 getlogin()
364 getlogin_r()
365 getnameinfo()
366 getnetbyaddr()
367 getnetbyname()
368 getnetent()
369 getopt() (if opterr is nonzero)
370 getprotobyname()
371 getprotobynumber()
372 getprotoent()
373 getpwent()
374 getpwnam()
375 getpwnam_r()
376 getpwuid()
377 getpwuid_r()
378 gets()
379 getservbyname()
380 getservbyport()
381 getservent()
382 getutxent()
383 getutxid()
384 getutxline()
385 getwc()
386 getwchar()
387 getwd() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
388 glob()
389 iconv_close()
390 iconv_open()
391 ioctl()
392 link()
393 linkat() [Added in POSIX.1-2008]
394 lio_listio() [Added in POSIX.1-2008]
395 localtime()
396 localtime_r()
397 lockf() [Added in POSIX.1-2008]
398 lseek()
399 lstat()
400 mkdir() [Added in POSIX.1-2008]
401 mkdirat() [Added in POSIX.1-2008]
402 mkdtemp() [Added in POSIX.1-2008]
403 mkfifo() [Added in POSIX.1-2008]
404 mkfifoat() [Added in POSIX.1-2008]
405 mknod() [Added in POSIX.1-2008]
406 mknodat() [Added in POSIX.1-2008]
407 mkstemp()
408 mktime()
409 nftw()
410 opendir()
411 openlog()
412 pathconf()
413 pclose()
414 perror()
415 popen()
416 posix_fadvise()
417 posix_fallocate()
418 posix_madvise()
419 posix_openpt()
420 posix_spawn()
421 posix_spawnp()
422 posix_trace_clear()
423 posix_trace_close()
424 posix_trace_create()
425 posix_trace_create_withlog()
426 posix_trace_eventtypelist_getnext_id()
427 posix_trace_eventtypelist_rewind()
428 posix_trace_flush()
429 posix_trace_get_attr()
430 posix_trace_get_filter()
431 posix_trace_get_status()
432 posix_trace_getnext_event()
433 posix_trace_open()
434 posix_trace_rewind()
435 posix_trace_set_filter()
436 posix_trace_shutdown()
437 posix_trace_timedgetnext_event()
438 posix_typed_mem_open()
439 printf()
440 psiginfo() [Added in POSIX.1-2008]
441 psignal() [Added in POSIX.1-2008]
442 pthread_rwlock_rdlock()
443 pthread_rwlock_timedrdlock()
444 pthread_rwlock_timedwrlock()
445 pthread_rwlock_wrlock()
446 putc()
447 putc_unlocked()
448 putchar()
449 putchar_unlocked()
450 puts()
451 pututxline()
452 putwc()
453 putwchar()
454 readdir()
455 readdir_r()
456 readlink() [Added in POSIX.1-2008]
457 readlinkat() [Added in POSIX.1-2008]
458 remove()
459 rename()
460 renameat() [Added in POSIX.1-2008]
461 rewind()
462 rewinddir()
463 scandir() [Added in POSIX.1-2008]
464 scanf()
465 seekdir()
466 semop()
467 setgrent()
468 sethostent()
469 setnetent()
470 setprotoent()
471 setpwent()
472 setservent()
473 setutxent()
474 sigpause() [Added in POSIX.1-2008]
475 stat()
476 strerror()
477 strerror_r()
478 strftime()
479 symlink()
480 symlinkat() [Added in POSIX.1-2008]
481 sync()
482 syslog()
483 tmpfile()
484 tmpnam()
485 ttyname()
486 ttyname_r()
487 tzset()
488 ungetc()
489 ungetwc()
490 unlink()
491 unlinkat() [Added in POSIX.1-2008]
492 utime() [Added in POSIX.1-2008]
493 utimensat() [Added in POSIX.1-2008]
494 utimes() [Added in POSIX.1-2008]
495 vdprintf() [Added in POSIX.1-2008]
496 vfprintf()
497 vfwprintf()
498 vprintf()
499 vwprintf()
500 wcsftime()
501 wordexp()
502 wprintf()
503 wscanf()
504 An implementation may also mark other functions not specified in the
506 standard as cancellation points. In particular, an implementation is
507 likely to mark any nonstandard function that may block as a cancella‐
508 tion point. (This includes most functions that can touch files.)
509 It should be noted that even if an application is not using asynchro‐
511 nous cancellation, that calling a function from the above list from an
512 asynchronous signal handler may cause the equivalent of asynchronous
513 cancellation. The underlying user code may not expect asynchronous
514 cancellation and the state of the user data may become inconsistent.
515 Therefore signals should be used with caution when entering a region of
516 deferred cancellation.
517 Compiling on Linux
519 On Linux, programs that use the Pthreads API should be compiled using
520 cc -pthread.
521 Linux implementations of POSIX threads
523 Over time, two threading implementations have been provided by the GNU
524 C library on Linux:
525 LinuxThreads
527 This is the original Pthreads implementation. Since glibc 2.4,
528 this implementation is no longer supported.
529 NPTL (Native POSIX Threads Library)
531 This is the modern Pthreads implementation. By comparison with
532 LinuxThreads, NPTL provides closer conformance to the require‐
533 ments of the POSIX.1 specification and better performance when
534 creating large numbers of threads. NPTL is available since
535 glibc 2.3.2, and requires features that are present in the Linux
536 2.6 kernel.
537 Both of these are so-called 1:1 implementations, meaning that each
539 thread maps to a kernel scheduling entity. Both threading implementa‐
540 tions employ the Linux clone(2) system call. In NPTL, thread synchro‐
541 nization primitives (mutexes, thread joining, and so on) are imple‐
542 mented using the Linux futex(2) system call.
543 LinuxThreads
545 The notable features of this implementation are the following:
546 - In addition to the main (initial) thread, and the threads that the
548 program creates using pthread_create(3), the implementation creates
549 a "manager" thread. This thread handles thread creation and termi‐
550 nation. (Problems can result if this thread is inadvertently
551 killed.)
552 - Signals are used internally by the implementation. On Linux 2.2 and
554 later, the first three real-time signals are used (see also sig‐
555 nal(7)). On older Linux kernels, SIGUSR1 and SIGUSR2 are used. Ap‐
556 plications must avoid the use of whichever set of signals is em‐
557 ployed by the implementation.
558 - Threads do not share process IDs. (In effect, LinuxThreads threads
560 are implemented as processes which share more information than
561 usual, but which do not share a common process ID.) LinuxThreads
562 threads (including the manager thread) are visible as separate pro‐
563 cesses using ps(1).
564 The LinuxThreads implementation deviates from the POSIX.1 specification
566 in a number of ways, including the following:
567 - Calls to getpid(2) return a different value in each thread.
569 - Calls to getppid(2) in threads other than the main thread return the
571 process ID of the manager thread; instead getppid(2) in these
572 threads should return the same value as getppid(2) in the main
573 thread.
574 - When one thread creates a new child process using fork(2), any
576 thread should be able to wait(2) on the child. However, the imple‐
577 mentation allows only the thread that created the child to wait(2)
578 on it.
579 - When a thread calls execve(2), all other threads are terminated (as
581 required by POSIX.1). However, the resulting process has the same
582 PID as the thread that called execve(2): it should have the same PID
583 as the main thread.
584 - Threads do not share user and group IDs. This can cause complica‐
586 tions with set-user-ID programs and can cause failures in Pthreads
587 functions if an application changes its credentials using seteuid(2)
588 or similar.
589 - Threads do not share a common session ID and process group ID.
591 - Threads do not share record locks created using fcntl(2).
593 - The information returned by times(2) and getrusage(2) is per-thread
595 rather than process-wide.
596 - Threads do not share semaphore undo values (see semop(2)).
598 - Threads do not share interval timers.
600 - Threads do not share a common nice value.
602 - POSIX.1 distinguishes the notions of signals that are directed to
604 the process as a whole and signals that are directed to individual
605 threads. According to POSIX.1, a process-directed signal (sent us‐
606 ing kill(2), for example) should be handled by a single, arbitrarily
607 selected thread within the process. LinuxThreads does not support
608 the notion of process-directed signals: signals may be sent only to
609 specific threads.
610 - Threads have distinct alternate signal stack settings. However, a
612 new thread's alternate signal stack settings are copied from the
613 thread that created it, so that the threads initially share an al‐
614 ternate signal stack. (A new thread should start with no alternate
615 signal stack defined. If two threads handle signals on their shared
616 alternate signal stack at the same time, unpredictable program fail‐
617 ures are likely to occur.)
618 NPTL
620 With NPTL, all of the threads in a process are placed in the same
621 thread group; all members of a thread group share the same PID. NPTL
622 does not employ a manager thread.
623 NPTL makes internal use of the first two real-time signals; these sig‐
625 nals cannot be used in applications. See nptl(7) for further details.
626 NPTL still has at least one nonconformance with POSIX.1:
628 - Threads do not share a common nice value.
630 Some NPTL nonconformances occur only with older kernels:
632 - The information returned by times(2) and getrusage(2) is per-thread
634 rather than process-wide (fixed in kernel 2.6.9).
635 - Threads do not share resource limits (fixed in kernel 2.6.10).
637 - Threads do not share interval timers (fixed in kernel 2.6.12).
639 - Only the main thread is permitted to start a new session using set‐
641 sid(2) (fixed in kernel 2.6.16).
642 - Only the main thread is permitted to make the process into a process
644 group leader using setpgid(2) (fixed in kernel 2.6.16).
645 - Threads have distinct alternate signal stack settings. However, a
647 new thread's alternate signal stack settings are copied from the
648 thread that created it, so that the threads initially share an al‐
649 ternate signal stack (fixed in kernel 2.6.16).
650 Note the following further points about the NPTL implementation:
652 - If the stack size soft resource limit (see the description of
654 RLIMIT_STACK in setrlimit(2)) is set to a value other than unlim‐
655 ited, then this value defines the default stack size for new
656 threads. To be effective, this limit must be set before the program
657 is executed, perhaps using the ulimit -s shell built-in command
658 (limit stacksize in the C shell).
659 Determining the threading implementation
661 Since glibc 2.3.2, the getconf(1) command can be used to determine the
662 system's threading implementation, for example:
663 bash$ getconf GNU_LIBPTHREAD_VERSION
665 NPTL 2.3.4
666 With older glibc versions, a command such as the following should be
668 sufficient to determine the default threading implementation:
669 bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
671 egrep -i 'threads|nptl'
672 Native POSIX Threads Library by Ulrich Drepper et al
673 Selecting the threading implementation: LD_ASSUME_KERNEL
675 On systems with a glibc that supports both LinuxThreads and NPTL (i.e.,
676 glibc 2.3.x), the LD_ASSUME_KERNEL environment variable can be used to
677 override the dynamic linker's default choice of threading implementa‐
678 tion. This variable tells the dynamic linker to assume that it is run‐
679 ning on top of a particular kernel version. By specifying a kernel
680 version that does not provide the support required by NPTL, we can
681 force the use of LinuxThreads. (The most likely reason for doing this
682 is to run a (broken) application that depends on some nonconformant be‐
683 havior in LinuxThreads.) For example:
684 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
686 awk '{print $3}' ) | egrep -i 'threads|nptl'
687 linuxthreads-0.10 by Xavier Leroy
688
690 clone(2), fork(2), futex(2), gettid(2), proc(5), attributes(7),
691 futex(7), nptl(7), sigevent(7), signal(7)
692 Various Pthreads manual pages, for example: pthread_atfork(3),
694 pthread_attr_init(3), pthread_cancel(3), pthread_cleanup_push(3),
695 pthread_cond_signal(3), pthread_cond_wait(3), pthread_create(3),
696 pthread_detach(3), pthread_equal(3), pthread_exit(3),
697 pthread_key_create(3), pthread_kill(3), pthread_mutex_lock(3),
698 pthread_mutex_unlock(3), pthread_mutexattr_destroy(3),
699 pthread_mutexattr_init(3), pthread_once(3), pthread_spin_init(3),
700 pthread_spin_lock(3), pthread_rwlockattr_setkind_np(3),
701 pthread_setcancelstate(3), pthread_setcanceltype(3),
702 pthread_setspecific(3), pthread_sigmask(3), pthread_sigqueue(3), and
703 pthread_testcancel(3)
704
706 This page is part of release 5.12 of the Linux man-pages project. A
707 description of the project, information about reporting bugs, and the
708 latest version of this page, can be found at
709 https://www.kernel.org/doc/man-pages/.
710Linux 2021-03-22 PTHREADS(7)