1PTHREADS(7)                Linux Programmer's Manual               PTHREADS(7)
2
3
4

NAME

6       pthreads - POSIX threads
7

DESCRIPTION

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
16       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
19       -  process ID
20
21       -  parent process ID
22
23       -  process group ID and session ID
24
25       -  controlling terminal
26
27       -  user and group IDs
28
29       -  open file descriptors
30
31       -  record locks (see fcntl(2))
32
33       -  signal dispositions
34
35       -  file mode creation mask (umask(2))
36
37       -  current directory (chdir(2)) and root directory (chroot(2))
38
39       -  interval timers (setitimer(2)) and POSIX timers (timer_create(2))
40
41       -  nice value (setpriority(2))
42
43       -  resource limits (setrlimit(2))
44
45       -  measurements of the consumption of CPU time (times(2)) and resources
46          (getrusage(2))
47
48       As well as the stack, POSIX.1 specifies that various  other  attributes
49       are distinct for each thread, including:
50
51       -  thread ID (the pthread_t data type)
52
53       -  signal mask (pthread_sigmask(3))
54
55       -  the errno variable
56
57       -  alternate signal stack (sigaltstack(2))
58
59       -  real-time scheduling policy and priority (sched(7))
60
61       The following Linux-specific features are also per-thread:
62
63       -  capabilities (see capabilities(7))
64
65       -  CPU affinity (sched_setaffinity(2))
66
67   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
73   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
79       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
83       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
88   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
93       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
96           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
188   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
193       Only  the  following  functions are required to be async-cancel-safe by
194       POSIX.1-2001 and POSIX.1-2008:
195
196           pthread_cancel()
197           pthread_setcancelstate()
198           pthread_setcanceltype()
199
200   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
207       The following functions are  required  to  be  cancellation  points  by
208       POSIX.1-2001 and/or POSIX.1-2008:
209
210           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
269       The  following  functions  may  be  cancellation  points  according  to
270       POSIX.1-2001 and/or POSIX.1-2008:
271
272           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
498       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
503   Compiling on Linux
504       On  Linux,  programs that use the Pthreads API should be compiled using
505       cc -pthread.
506
507   Linux implementations of POSIX threads
508       Over time, two threading implementations have been provided by the  GNU
509       C library on Linux:
510
511       LinuxThreads
512              This  is the original Pthreads implementation.  Since glibc 2.4,
513              this implementation is no longer supported.
514
515       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
523       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
529   LinuxThreads
530       The notable features of this implementation are the following:
531
532       -  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
538       -  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
544       -  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
550       The LinuxThreads implementation deviates from the POSIX.1 specification
551       in a number of ways, including the following:
552
553       -  Calls to getpid(2) return a different value in each thread.
554
555       -  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
560       -  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
565       -  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
570       -  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
575       -  Threads do not share a common session ID and process group ID.
576
577       -  Threads do not share record locks created using fcntl(2).
578
579       -  The information returned by times(2) and getrusage(2) is  per-thread
580          rather than process-wide.
581
582       -  Threads do not share semaphore undo values (see semop(2)).
583
584       -  Threads do not share interval timers.
585
586       -  Threads do not share a common nice value.
587
588       -  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
596       -  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
604   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
609       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
612       NPTL still has at least one nonconformance with POSIX.1:
613
614       -  Threads do not share a common nice value.
615
616       Some NPTL nonconformances occur only with older kernels:
617
618       -  The information returned by times(2) and getrusage(2) is  per-thread
619          rather than process-wide (fixed in kernel 2.6.9).
620
621       -  Threads do not share resource limits (fixed in kernel 2.6.10).
622
623       -  Threads do not share interval timers (fixed in kernel 2.6.12).
624
625       -  Only  the main thread is permitted to start a new session using set‐
626          sid(2) (fixed in kernel 2.6.16).
627
628       -  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
631       -  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
636       Note the following further points about the NPTL implementation:
637
638       -  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
645   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
649           bash$ getconf GNU_LIBPTHREAD_VERSION
650           NPTL 2.3.4
651
652       With older glibc versions, a command such as the  following  should  be
653       sufficient to determine the default threading implementation:
654
655           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
659   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
670           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

SEE ALSO

675       clone(2), fork(2), futex(2), gettid(2), proc(5), attributes(7),
676       futex(7), nptl(7), sigevent(7), signal(7)
677
678       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

COLOPHON

691       This page is part of release 5.02 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/.
695
696
697
698Linux                             2019-03-06                       PTHREADS(7)
Impressum