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

SEE ALSO

658       clone(2), futex(2), gettid(2), proc(5), futex(7), signal(7),
659       and  various  Pthreads manual pages, for example: pthread_attr_init(3),
660       pthread_atfork(3),     pthread_cancel(3),      pthread_cleanup_push(3),
661       pthread_cond_signal(3),     pthread_cond_wait(3),    pthread_create(3),
662       pthread_detach(3), pthread_equal(3), pthread_exit(3),  pthread_key_cre‐
663       ate(3),             pthread_kill(3),             pthread_mutex_lock(3),
664       pthread_mutex_unlock(3),  pthread_once(3),   pthread_setcancelstate(3),
665       pthread_setcanceltype(3),  pthread_setspecific(3),  pthread_sigmask(3),
666       and pthread_testcancel(3)
667

COLOPHON

669       This page is part of release 3.25 of the Linux  man-pages  project.   A
670       description  of  the project, and information about reporting bugs, can
671       be found at http://www.kernel.org/doc/man-pages/.
672
673
674
675Linux                             2008-11-18                       PTHREADS(7)
Impressum