1pthreads(7)            Miscellaneous Information 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.  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
76   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
82       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
86       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
91   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
96       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
99           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
193   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
198       Only the following functions are required to  be  async-cancel-safe  by
199       POSIX.1-2001 and POSIX.1-2008:
200
201           pthread_cancel()
202           pthread_setcancelstate()
203           pthread_setcanceltype()
204
205   Cancelation points
206       POSIX.1  specifies that certain functions must, and certain other func‐
207       tions may, be cancelation points.  If a thread is cancelable, its  can‐
208       celability  type  is deferred, and a cancelation request is pending for
209       the thread, then the thread is canceled when it calls a  function  that
210       is a cancelation point.
211
212       The  following  functions  are  required  to  be  cancelation points by
213       POSIX.1-2001 and/or POSIX.1-2008:
214
215           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
274       The  following  functions  may  be  cancelation  points  according   to
275       POSIX.1-2001 and/or POSIX.1-2008:
276
277           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
505       An  implementation  may  also mark other functions not specified in the
506       standard as cancelation points.  In particular,  an  implementation  is
507       likely to mark any nonstandard function that may block as a cancelation
508       point.  (This includes most functions that can touch files.)
509
510       It should be noted that even if an application is not  using  asynchro‐
511       nous  cancelation,  that calling a function from the above list from an
512       asynchronous signal handler may cause the  equivalent  of  asynchronous
513       cancelation.  The underlying user code may not expect asynchronous can‐
514       celation 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 cancelation.
517
518   Compiling on Linux
519       On Linux, programs that use the Pthreads API should be  compiled  using
520       cc -pthread.
521
522   Linux implementations of POSIX threads
523       Over  time, two threading implementations have been provided by the GNU
524       C library on Linux:
525
526       LinuxThreads
527              This is the original Pthreads implementation.  Since glibc  2.4,
528              this implementation is no longer supported.
529
530       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
538       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
544   LinuxThreads
545       The notable features of this implementation are the following:
546
547       •  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
553       •  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
559       •  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
565       The LinuxThreads implementation deviates from the POSIX.1 specification
566       in a number of ways, including the following:
567
568       •  Calls to getpid(2) return a different value in each thread.
569
570       •  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
575       •  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
580       •  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
585       •  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
590       •  Threads do not share a common session ID and process group ID.
591
592       •  Threads do not share record locks created using fcntl(2).
593
594       •  The  information returned by times(2) and getrusage(2) is per-thread
595          rather than process-wide.
596
597       •  Threads do not share semaphore undo values (see semop(2)).
598
599       •  Threads do not share interval timers.
600
601       •  Threads do not share a common nice value.
602
603       •  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
611       •  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
619   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
624       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
627       NPTL still has at least one nonconformance with POSIX.1:
628
629       •  Threads do not share a common nice value.
630
631       Some NPTL nonconformances occur only with older kernels:
632
633       •  The  information returned by times(2) and getrusage(2) is per-thread
634          rather than process-wide (fixed in Linux 2.6.9).
635
636       •  Threads do not share resource limits (fixed in Linux 2.6.10).
637
638       •  Threads do not share interval timers (fixed in Linux 2.6.12).
639
640       •  Only the main thread is permitted to start a new session using  set‐
641          sid(2) (fixed in Linux 2.6.16).
642
643       •  Only the main thread is permitted to make the process into a process
644          group leader using setpgid(2) (fixed in Linux 2.6.16).
645
646       •  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 Linux 2.6.16).
650
651       Note the following further points about the NPTL implementation:
652
653       •  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
660   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
664           bash$ getconf GNU_LIBPTHREAD_VERSION
665           NPTL 2.3.4
666
667       With  older  glibc  versions, a command such as the following should be
668       sufficient to determine the default threading implementation:
669
670           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
674   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
685           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

SEE ALSO

690       clone(2), fork(2), futex(2), gettid(2), proc(5), attributes(7),
691       futex(7), nptl(7), sigevent(7), signal(7)
692
693       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
705
706
707Linux man-pages 6.05              2023-03-18                       pthreads(7)
Impressum