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_setscheduler(2) and
60 sched_setparam(2))
61 The following Linux-specific features are also per-thread:
63 - capabilities (see capabilities(7))
65 - CPU affinity (sched_setaffinity(2))
67 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 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 guaranteed to be unique only
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 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 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 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 Async-cancel-safe functions
185 An async-cancel-safe function is one that can be safely called in an
186 application where asynchronous cancelability is enabled (see
187 pthread_setcancelstate(3)).
188 Only the following functions are required to be async-cancel-safe by
190 POSIX.1-2001 and POSIX.1-2008:
191 pthread_cancel()
193 pthread_setcancelstate()
194 pthread_setcanceltype()
195 Cancellation points
197 POSIX.1 specifies that certain functions must, and certain other func‐
198 tions may, be cancellation points. If a thread is cancelable, its can‐
199 celability type is deferred, and a cancellation request is pending for
200 the thread, then the thread is canceled when it calls a function that
201 is a cancellation point.
202 The following functions are required to be cancellation points by
204 POSIX.1-2001 and/or POSIX.1-2008:
205 accept()
207 aio_suspend()
208 clock_nanosleep()
209 close()
210 connect()
211 creat()
212 fcntl() F_SETLKW
213 fdatasync()
214 fsync()
215 getmsg()
216 getpmsg()
217 lockf() F_LOCK
218 mq_receive()
219 mq_send()
220 mq_timedreceive()
221 mq_timedsend()
222 msgrcv()
223 msgsnd()
224 msync()
225 nanosleep()
226 open()
227 openat() [Added in POSIX.1-2008]
228 pause()
229 poll()
230 pread()
231 pselect()
232 pthread_cond_timedwait()
233 pthread_cond_wait()
234 pthread_join()
235 pthread_testcancel()
236 putmsg()
237 putpmsg()
238 pwrite()
239 read()
240 readv()
241 recv()
242 recvfrom()
243 recvmsg()
244 select()
245 sem_timedwait()
246 sem_wait()
247 send()
248 sendmsg()
249 sendto()
250 sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
251 sigsuspend()
252 sigtimedwait()
253 sigwait()
254 sigwaitinfo()
255 sleep()
256 system()
257 tcdrain()
258 usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
259 wait()
260 waitid()
261 waitpid()
262 write()
263 writev()
264 The following functions may be cancellation points according to
266 POSIX.1-2001 and/or POSIX.1-2008:
267 access()
269 asctime()
270 asctime_r()
271 catclose()
272 catgets()
273 catopen()
274 chmod() [Added in POSIX.1-2008]
275 chown() [Added in POSIX.1-2008]
276 closedir()
277 closelog()
278 ctermid()
279 ctime()
280 ctime_r()
281 dbm_close()
282 dbm_delete()
283 dbm_fetch()
284 dbm_nextkey()
285 dbm_open()
286 dbm_store()
287 dlclose()
288 dlopen()
289 dprintf() [Added in POSIX.1-2008]
290 endgrent()
291 endhostent()
292 endnetent()
293 endprotoent()
294 endpwent()
295 endservent()
296 endutxent()
297 faccessat() [Added in POSIX.1-2008]
298 fchmod() [Added in POSIX.1-2008]
299 fchmodat() [Added in POSIX.1-2008]
300 fchown() [Added in POSIX.1-2008]
301 fchownat() [Added in POSIX.1-2008]
302 fclose()
303 fcntl() (for any value of cmd argument)
304 fflush()
305 fgetc()
306 fgetpos()
307 fgets()
308 fgetwc()
309 fgetws()
310 fmtmsg()
311 fopen()
312 fpathconf()
313 fprintf()
314 fputc()
315 fputs()
316 fputwc()
317 fputws()
318 fread()
319 freopen()
320 fscanf()
321 fseek()
322 fseeko()
323 fsetpos()
324 fstat()
325 fstatat() [Added in POSIX.1-2008]
326 ftell()
327 ftello()
328 ftw()
329 futimens() [Added in POSIX.1-2008]
330 fwprintf()
331 fwrite()
332 fwscanf()
333 getaddrinfo()
334 getc()
335 getc_unlocked()
336 getchar()
337 getchar_unlocked()
338 getcwd()
339 getdate()
340 getdelim() [Added in POSIX.1-2008]
341 getgrent()
342 getgrgid()
343 getgrgid_r()
344 getgrnam()
345 getgrnam_r()
346 gethostbyaddr() [SUSv3 only (function removed in POSIX.1-2008)]
347 gethostbyname() [SUSv3 only (function removed in POSIX.1-2008)]
348 gethostent()
349 gethostid()
350 gethostname()
351 getline() [Added in POSIX.1-2008]
352 getlogin()
353 getlogin_r()
354 getnameinfo()
355 getnetbyaddr()
356 getnetbyname()
357 getnetent()
358 getopt() (if opterr is nonzero)
359 getprotobyname()
360 getprotobynumber()
361 getprotoent()
362 getpwent()
363 getpwnam()
364 getpwnam_r()
365 getpwuid()
366 getpwuid_r()
367 gets()
368 getservbyname()
369 getservbyport()
370 getservent()
371 getutxent()
372 getutxid()
373 getutxline()
374 getwc()
375 getwchar()
376 getwd() [SUSv3 only (function removed in POSIX.1-2008)]
377 glob()
378 iconv_close()
379 iconv_open()
380 ioctl()
381 link()
382 linkat() [Added in POSIX.1-2008]
383 lio_listio() [Added in POSIX.1-2008]
384 localtime()
385 localtime_r()
386 lockf() [Added in POSIX.1-2008]
387 lseek()
388 lstat()
389 mkdir() [Added in POSIX.1-2008]
390 mkdirat() [Added in POSIX.1-2008]
391 mkdtemp() [Added in POSIX.1-2008]
392 mkfifo() [Added in POSIX.1-2008]
393 mkfifoat() [Added in POSIX.1-2008]
394 mknod() [Added in POSIX.1-2008]
395 mknodat() [Added in POSIX.1-2008]
396 mkstemp()
397 mktime()
398 nftw()
399 opendir()
400 openlog()
401 pathconf()
402 pclose()
403 perror()
404 popen()
405 posix_fadvise()
406 posix_fallocate()
407 posix_madvise()
408 posix_openpt()
409 posix_spawn()
410 posix_spawnp()
411 posix_trace_clear()
412 posix_trace_close()
413 posix_trace_create()
414 posix_trace_create_withlog()
415 posix_trace_eventtypelist_getnext_id()
416 posix_trace_eventtypelist_rewind()
417 posix_trace_flush()
418 posix_trace_get_attr()
419 posix_trace_get_filter()
420 posix_trace_get_status()
421 posix_trace_getnext_event()
422 posix_trace_open()
423 posix_trace_rewind()
424 posix_trace_set_filter()
425 posix_trace_shutdown()
426 posix_trace_timedgetnext_event()
427 posix_typed_mem_open()
428 printf()
429 psiginfo() [Added in POSIX.1-2008]
430 psignal() [Added in POSIX.1-2008]
431 pthread_rwlock_rdlock()
432 pthread_rwlock_timedrdlock()
433 pthread_rwlock_timedwrlock()
434 pthread_rwlock_wrlock()
435 putc()
436 putc_unlocked()
437 putchar()
438 putchar_unlocked()
439 puts()
440 pututxline()
441 putwc()
442 putwchar()
443 readdir()
444 readdir_r()
445 readlink() [Added in POSIX.1-2008]
446 readlinkat() [Added in POSIX.1-2008]
447 remove()
448 rename()
449 renameat() [Added in POSIX.1-2008]
450 rewind()
451 rewinddir()
452 scandir() [Added in POSIX.1-2008]
453 scanf()
454 seekdir()
455 semop()
456 setgrent()
457 sethostent()
458 setnetent()
459 setprotoent()
460 setpwent()
461 setservent()
462 setutxent()
463 sigpause() [Added in POSIX.1-2008]
464 stat()
465 strerror()
466 strerror_r()
467 strftime()
468 symlink()
469 symlinkat() [Added in POSIX.1-2008]
470 sync()
471 syslog()
472 tmpfile()
473 tmpnam()
474 ttyname()
475 ttyname_r()
476 tzset()
477 ungetc()
478 ungetwc()
479 unlink()
480 unlinkat() [Added in POSIX.1-2008]
481 utime() [Added in POSIX.1-2008]
482 utimensat() [Added in POSIX.1-2008]
483 utimes() [Added in POSIX.1-2008]
484 vdprintf() [Added in POSIX.1-2008]
485 vfprintf()
486 vfwprintf()
487 vprintf()
488 vwprintf()
489 wcsftime()
490 wordexp()
491 wprintf()
492 wscanf()
493 An implementation may also mark other functions not specified in the
495 standard as cancellation points. In particular, an implementation is
496 likely to mark any nonstandard function that may block as a cancella‐
497 tion point. (This includes most functions that can touch files.)
498 Compiling on Linux
500 On Linux, programs that use the Pthreads API should be compiled using
501 cc -pthread.
502 Linux implementations of POSIX threads
504 Over time, two threading implementations have been provided by the GNU
505 C library on Linux:
506 LinuxThreads
508 This is the original Pthreads implementation. Since glibc 2.4,
509 this implementation is no longer supported.
510 NPTL (Native POSIX Threads Library)
512 This is the modern Pthreads implementation. By comparison with
513 LinuxThreads, NPTL provides closer conformance to the require‐
514 ments of the POSIX.1 specification and better performance when
515 creating large numbers of threads. NPTL is available since
516 glibc 2.3.2, and requires features that are present in the Linux
517 2.6 kernel.
518 Both of these are so-called 1:1 implementations, meaning that each
520 thread maps to a kernel scheduling entity. Both threading implementa‐
521 tions employ the Linux clone(2) system call. In NPTL, thread synchro‐
522 nization primitives (mutexes, thread joining, and so on) are imple‐
523 mented using the Linux futex(2) system call.
524 LinuxThreads
526 The notable features of this implementation are the following:
527 - In addition to the main (initial) thread, and the threads that the
529 program creates using pthread_create(3), the implementation creates
530 a "manager" thread. This thread handles thread creation and termi‐
531 nation. (Problems can result if this thread is inadvertently
532 killed.)
533 - Signals are used internally by the implementation. On Linux 2.2 and
535 later, the first three real-time signals are used (see also sig‐
536 nal(7)). On older Linux kernels, SIGUSR1 and SIGUSR2 are used.
537 Applications must avoid the use of whichever set of signals is
538 employed by the implementation.
539 - Threads do not share process IDs. (In effect, LinuxThreads threads
541 are implemented as processes which share more information than
542 usual, but which do not share a common process ID.) LinuxThreads
543 threads (including the manager thread) are visible as separate pro‐
544 cesses using ps(1).
545 The LinuxThreads implementation deviates from the POSIX.1 specification
547 in a number of ways, including the following:
548 - Calls to getpid(2) return a different value in each thread.
550 - Calls to getppid(2) in threads other than the main thread return the
552 process ID of the manager thread; instead getppid(2) in these
553 threads should return the same value as getppid(2) in the main
554 thread.
555 - When one thread creates a new child process using fork(2), any
557 thread should be able to wait(2) on the child. However, the imple‐
558 mentation only allows the thread that created the child to wait(2)
559 on it.
560 - When a thread calls execve(2), all other threads are terminated (as
562 required by POSIX.1). However, the resulting process has the same
563 PID as the thread that called execve(2): it should have the same PID
564 as the main thread.
565 - Threads do not share user and group IDs. This can cause complica‐
567 tions with set-user-ID programs and can cause failures in Pthreads
568 functions if an application changes its credentials using seteuid(2)
569 or similar.
570 - Threads do not share a common session ID and process group ID.
572 - Threads do not share record locks created using fcntl(2).
574 - The information returned by times(2) and getrusage(2) is per-thread
576 rather than process-wide.
577 - Threads do not share semaphore undo values (see semop(2)).
579 - Threads do not share interval timers.
581 - Threads do not share a common nice value.
583 - POSIX.1 distinguishes the notions of signals that are directed to
585 the process as a whole and signals that are directed to individual
586 threads. According to POSIX.1, a process-directed signal (sent
587 using kill(2), for example) should be handled by a single, arbitrar‐
588 ily selected thread within the process. LinuxThreads does not sup‐
589 port the notion of process-directed signals: signals may be sent
590 only to specific threads.
591 - Threads have distinct alternate signal stack settings. However, a
593 new thread's alternate signal stack settings are copied from the
594 thread that created it, so that the threads initially share an
595 alternate signal stack. (A new thread should start with no alter‐
596 nate signal stack defined. If two threads handle signals on their
597 shared alternate signal stack at the same time, unpredictable pro‐
598 gram failures are likely to occur.)
599 NPTL
601 With NPTL, all of the threads in a process are placed in the same
602 thread group; all members of a thread group share the same PID. NPTL
603 does not employ a manager thread. NPTL makes internal use of the first
604 two real-time signals (see also signal(7)); these signals cannot be
605 used in applications.
606 NPTL still has at least one nonconformance with POSIX.1:
608 - Threads do not share a common nice value.
610 Some NPTL nonconformances occur only with older kernels:
612 - The information returned by times(2) and getrusage(2) is per-thread
614 rather than process-wide (fixed in kernel 2.6.9).
615 - Threads do not share resource limits (fixed in kernel 2.6.10).
617 - Threads do not share interval timers (fixed in kernel 2.6.12).
619 - Only the main thread is permitted to start a new session using set‐
621 sid(2) (fixed in kernel 2.6.16).
622 - Only the main thread is permitted to make the process into a process
624 group leader using setpgid(2) (fixed in kernel 2.6.16).
625 - Threads have distinct alternate signal stack settings. However, a
627 new thread's alternate signal stack settings are copied from the
628 thread that created it, so that the threads initially share an
629 alternate signal stack (fixed in kernel 2.6.16).
630 Note the following further points about the NPTL implementation:
632 - If the stack size soft resource limit (see the description of
634 RLIMIT_STACK in setrlimit(2)) is set to a value other than unlim‐
635 ited, then this value defines the default stack size for new
636 threads. To be effective, this limit must be set before the program
637 is executed, perhaps using the ulimit -s shell built-in command
638 (limit stacksize in the C shell).
639 Determining the threading implementation
641 Since glibc 2.3.2, the getconf(1) command can be used to determine the
642 system's threading implementation, for example:
643 bash$ getconf GNU_LIBPTHREAD_VERSION
645 NPTL 2.3.4
646 With older glibc versions, a command such as the following should be
648 sufficient to determine the default threading implementation:
649 bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \
651 egrep -i 'threads|nptl'
652 Native POSIX Threads Library by Ulrich Drepper et al
653 Selecting the threading implementation: LD_ASSUME_KERNEL
655 On systems with a glibc that supports both LinuxThreads and NPTL (i.e.,
656 glibc 2.3.x), the LD_ASSUME_KERNEL environment variable can be used to
657 override the dynamic linker's default choice of threading implementa‐
658 tion. This variable tells the dynamic linker to assume that it is run‐
659 ning on top of a particular kernel version. By specifying a kernel
660 version that does not provide the support required by NPTL, we can
661 force the use of LinuxThreads. (The most likely reason for doing this
662 is to run a (broken) application that depends on some nonconformant
663 behavior in LinuxThreads.) For example:
664 bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \
666 awk '{print $3}' ) | egrep -i 'threads|ntpl'
667 linuxthreads-0.10 by Xavier Leroy
668
670 clone(2), futex(2), gettid(2), proc(5), futex(7), sigevent(7),
671 signal(7),
672 Various Pthreads manual pages, for example: pthread_attr_init(3),
674 pthread_atfork(3), pthread_cancel(3), pthread_cleanup_push(3),
675 pthread_cond_signal(3), pthread_cond_wait(3), pthread_create(3),
676 pthread_detach(3), pthread_equal(3), pthread_exit(3),
677 pthread_key_create(3), pthread_kill(3), pthread_mutex_lock(3),
678 pthread_mutex_unlock(3), pthread_once(3), pthread_setcancelstate(3),
679 pthread_setcanceltype(3), pthread_setspecific(3), pthread_sigmask(3),
680 pthread_sigqueue(3), and pthread_testcancel(3)
681
683 This page is part of release 3.53 of the Linux man-pages project. A
684 description of the project, and information about reporting bugs, can
685 be found at http://www.kernel.org/doc/man-pages/.
686Linux 2010-11-14 PTHREADS(7)