Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 134 insertions, 0 deletions

diff --git a/man/man3/pthread_join.3 b/man/man3/pthread_join.3
new file mode 100644
index 0000000..1d3fbb8
--- /dev/null
+++ b/man/man3/pthread_join.3
@@ -0,0 +1,134 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_join 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+pthread_join \- join with a terminated thread
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.P
+.BI "int pthread_join(pthread_t " thread ", void **" retval );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_join ()
+function waits for the thread specified by
+.I thread
+to terminate.
+If that thread has already terminated, then
+.BR pthread_join ()
+returns immediately.
+The thread specified by
+.I thread
+must be joinable.
+.P
+If
+.I retval
+is not NULL, then
+.BR pthread_join ()
+copies the exit status of the target thread
+(i.e., the value that the target thread supplied to
+.BR pthread_exit (3))
+into the location pointed to by
+.IR retval .
+If the target thread was canceled, then
+.B PTHREAD_CANCELED
+is placed in the location pointed to by
+.IR retval .
+.P
+If multiple threads simultaneously try to join with the same thread,
+the results are undefined.
+If the thread calling
+.BR pthread_join ()
+is canceled, then the target thread will remain joinable
+(i.e., it will not be detached).
+.SH RETURN VALUE
+On success,
+.BR pthread_join ()
+returns 0;
+on error, it returns an error number.
+.SH ERRORS
+.TP
+.B EDEADLK
+A deadlock was detected
+.\" The following verified by testing on glibc 2.8/NPTL:
+(e.g., two threads tried to join with each other);
+or
+.\" The following verified by testing on glibc 2.8/NPTL:
+.I thread
+specifies the calling thread.
+.TP
+.B EINVAL
+.I thread
+is not a joinable thread.
+.TP
+.B EINVAL
+Another thread is already waiting to join with this thread.
+.\" POSIX.1-2001 does not specify this error case.
+.TP
+.B ESRCH
+No thread with the ID
+.I thread
+could be found.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR pthread_join ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+After a successful call to
+.BR pthread_join (),
+the caller is guaranteed that the target thread has terminated.
+The caller may then choose to do any clean-up that is required
+after termination of the thread (e.g., freeing memory or other
+resources that were allocated to the target thread).
+.P
+Joining with a thread that has previously been joined results in
+undefined behavior.
+.P
+Failure to join with a thread that is joinable
+(i.e., one that is not detached),
+produces a "zombie thread".
+Avoid doing this,
+since each zombie thread consumes some system resources,
+and when enough zombie threads have accumulated,
+it will no longer be possible to create new threads (or processes).
+.P
+There is no pthreads analog of
+.IR "waitpid(\-1,\ &status,\ 0)" ,
+that is, "join with any terminated thread".
+If you believe you need this functionality,
+you probably need to rethink your application design.
+.P
+All of the threads in a process are peers:
+any thread can join with any other thread in the process.
+.SH EXAMPLES
+See
+.BR pthread_create (3).
+.SH SEE ALSO
+.BR pthread_cancel (3),
+.BR pthread_create (3),
+.BR pthread_detach (3),
+.BR pthread_exit (3),
+.BR pthread_tryjoin_np (3),
+.BR pthreads (7)