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 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 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 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 The following functions are required to be cancellation points by
192 POSIX.1-2001 and/or POSIX.1-2008:
193 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 The following functions may be cancellation points according to
254 POSIX.1-2001 and/or POSIX.1-2008:
255 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 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 Compiling on Linux
488 On Linux, programs that use the Pthreads API should be compiled using
489 cc -pthread.
490 Linux Implementations of POSIX Threads
492 Over time, two threading implementations have been provided by the GNU
493 C library on Linux:
494 LinuxThreads
496 This is the original Pthreads implementation. Since glibc 2.4,
497 this implementation is no longer supported.
498 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 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 LinuxThreads
514 The notable features of this implementation are the following:
515 - 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 - 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 - 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 The LinuxThreads implementation deviates from the POSIX.1 specification
535 in a number of ways, including the following:
536 - Calls to getpid(2) return a different value in each thread.
538 - 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 - 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 - 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 - 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 - Threads do not share a common session ID and process group ID.
560 - Threads do not share record locks created using fcntl(2).
562 - The information returned by times(2) and getrusage(2) is per-thread
564 rather than process-wide.
565 - Threads do not share semaphore undo values (see semop(2)).
567 - Threads do not share interval timers.
569 - Threads do not share a common nice value.
571 - 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 - 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 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 NPTL still has at least one nonconformance with POSIX.1:
596 - Threads do not share a common nice value.
598 Some NPTL nonconformances only occur with older kernels:
600 - The information returned by times(2) and getrusage(2) is per-thread
602 rather than process-wide (fixed in kernel 2.6.9).
603 - Threads do not share resource limits (fixed in kernel 2.6.10).
605 - Threads do not share interval timers (fixed in kernel 2.6.12).
607 - Only the main thread is permitted to start a new session using set‐
609 sid(2) (fixed in kernel 2.6.16).
610 - 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 - 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 Note the following further points about the NPTL implementation:
620 - 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 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 bash$ getconf GNU_LIBPTHREAD_VERSION
633 NPTL 2.3.4
634 With older glibc versions, a command such as the following should be
636 sufficient to determine the default threading implementation:
637 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 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 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
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
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/.
672Linux 2008-11-18 PTHREADS(7)