| 1 |
'\" t |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pthread_exit 3 2025-05-17 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pthread_exit \- terminate calling thread |
| 9 |
.SH LIBRARY |
| 10 |
POSIX threads library |
| 11 |
.RI ( libpthread ,\~ \-lpthread ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <pthread.h> |
| 15 |
.P |
| 16 |
.BI "[[noreturn]] void pthread_exit(void *" retval ); |
| 17 |
.fi |
| 18 |
.SH DESCRIPTION |
| 19 |
The |
| 20 |
.BR pthread_exit () |
| 21 |
function terminates the calling thread and returns a value via |
| 22 |
.I retval |
| 23 |
that (if the thread is joinable) |
| 24 |
is available to another thread in the same process that calls |
| 25 |
.BR pthread_join (3). |
| 26 |
.P |
| 27 |
Any clean-up handlers established by |
| 28 |
.BR pthread_cleanup_push (3) |
| 29 |
that have not yet been popped, |
| 30 |
are popped (in the reverse of the order in which they were pushed) |
| 31 |
and executed. |
| 32 |
If the thread has any thread-specific data, then, |
| 33 |
after the clean-up handlers have been executed, |
| 34 |
the corresponding destructor functions are called, |
| 35 |
in an unspecified order. |
| 36 |
.P |
| 37 |
When a thread terminates, |
| 38 |
process-shared resources (e.g., mutexes, condition variables, |
| 39 |
semaphores, and file descriptors) are not released, |
| 40 |
and functions registered using |
| 41 |
.BR atexit (3) |
| 42 |
are not called. |
| 43 |
.P |
| 44 |
After the last thread in a process terminates, |
| 45 |
the process terminates as by calling |
| 46 |
.BR exit (3) |
| 47 |
with an exit status of zero; |
| 48 |
thus, process-shared resources |
| 49 |
are released and functions registered using |
| 50 |
.BR atexit (3) |
| 51 |
are called. |
| 52 |
.SH RETURN VALUE |
| 53 |
This function does not return to the caller. |
| 54 |
.SH ERRORS |
| 55 |
This function always succeeds. |
| 56 |
.SH ATTRIBUTES |
| 57 |
For an explanation of the terms used in this section, see |
| 58 |
.BR attributes (7). |
| 59 |
.TS |
| 60 |
allbox; |
| 61 |
lbx lb lb |
| 62 |
l l l. |
| 63 |
Interface Attribute Value |
| 64 |
T{ |
| 65 |
.na |
| 66 |
.nh |
| 67 |
.BR pthread_exit () |
| 68 |
T} Thread safety MT-Safe |
| 69 |
.TE |
| 70 |
.SH STANDARDS |
| 71 |
POSIX.1-2008. |
| 72 |
.SH HISTORY |
| 73 |
POSIX.1-2001. |
| 74 |
.SH NOTES |
| 75 |
Performing a return from the start function of any thread other |
| 76 |
than the main thread results in an implicit call to |
| 77 |
.BR pthread_exit (), |
| 78 |
using the function's return value as the thread's exit status. |
| 79 |
.P |
| 80 |
To allow other threads to continue execution, |
| 81 |
the main thread should terminate by calling |
| 82 |
.BR pthread_exit () |
| 83 |
rather than |
| 84 |
.BR exit (3). |
| 85 |
.P |
| 86 |
The value pointed to by |
| 87 |
.I retval |
| 88 |
should not be located on the calling thread's stack, |
| 89 |
since the contents of that stack are undefined after the thread terminates. |
| 90 |
.SH BUGS |
| 91 |
Currently, |
| 92 |
.\" Linux 2.6.27 |
| 93 |
there are limitations in the kernel implementation logic for |
| 94 |
.BR wait (2)ing |
| 95 |
on a stopped thread group with a dead thread group leader. |
| 96 |
This can manifest in problems such as a locked terminal if a stop signal is |
| 97 |
sent to a foreground process whose thread group leader has already called |
| 98 |
.BR pthread_exit (). |
| 99 |
.\" FIXME . review a later kernel to see if this gets fixed |
| 100 |
.\" http://thread.gmane.org/gmane.linux.kernel/611611 |
| 101 |
.\" http://marc.info/?l=linux-kernel&m=122525468300823&w=2 |
| 102 |
.SH SEE ALSO |
| 103 |
.BR pthread_create (3), |
| 104 |
.BR pthread_join (3), |
| 105 |
.BR pthreads (7) |