Debian Codegraph @

upstream/debian-unstable/man3/pthread_exit.3

raw
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)