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