Merging upstream version 6.8.

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

1 files changed, 237 insertions, 0 deletions

diff --git a/man/man3/pthread_cancel.3 b/man/man3/pthread_cancel.3
new file mode 100644
index 0000000..99232b4
--- /dev/null
+++ b/man/man3/pthread_cancel.3
@@ -0,0 +1,237 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_cancel 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+pthread_cancel \- send a cancelation request to a thread
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.P
+.BI "int pthread_cancel(pthread_t " thread );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_cancel ()
+function sends a cancelation request to the thread
+.IR thread .
+Whether and when the target thread
+reacts to the cancelation request depends on
+two attributes that are under the control of that thread:
+its cancelability
+.I state
+and
+.IR type .
+.P
+A thread's cancelability state, determined by
+.BR pthread_setcancelstate (3),
+can be
+.I enabled
+(the default for new threads) or
+.IR disabled .
+If a thread has disabled cancelation,
+then a cancelation request remains queued until the thread
+enables cancelation.
+If a thread has enabled cancelation,
+then its cancelability type determines when cancelation occurs.
+.P
+A thread's cancelation type, determined by
+.BR pthread_setcanceltype (3),
+may be either
+.I asynchronous
+or
+.I deferred
+(the default for new threads).
+Asynchronous cancelability
+means that the thread can be canceled at any time
+(usually immediately, but the system does not guarantee this).
+Deferred cancelability means that cancelation will be delayed until
+the thread next calls a function that is a
+.IR "cancelation point" .
+A list of functions that are or may be cancelation points is provided in
+.BR pthreads (7).
+.P
+When a cancelation requested is acted on, the following steps occur for
+.I thread
+(in this order):
+.IP (1) 5
+Cancelation clean-up handlers are popped
+(in the reverse of the order in which they were pushed) and called.
+(See
+.BR pthread_cleanup_push (3).)
+.IP (2)
+Thread-specific data destructors are called,
+in an unspecified order.
+(See
+.BR pthread_key_create (3).)
+.IP (3)
+The thread is terminated.
+(See
+.BR pthread_exit (3).)
+.P
+The above steps happen asynchronously with respect to the
+.BR pthread_cancel ()
+call;
+the return status of
+.BR pthread_cancel ()
+merely informs the caller whether the cancelation request
+was successfully queued.
+.P
+After a canceled thread has terminated,
+a join with that thread using
+.BR pthread_join (3)
+obtains
+.B PTHREAD_CANCELED
+as the thread's exit status.
+(Joining with a thread is the only way to know that cancelation
+has completed.)
+.SH RETURN VALUE
+On success,
+.BR pthread_cancel ()
+returns 0;
+on error, it returns a nonzero error number.
+.SH ERRORS
+.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_cancel ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+On Linux, cancelation is implemented using signals.
+Under the NPTL threading implementation,
+the first real-time signal (i.e., signal 32) is used for this purpose.
+On LinuxThreads, the second real-time signal is used,
+if real-time signals are available, otherwise
+.B SIGUSR2
+is used.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.0
+POSIX.1-2001.
+.SH EXAMPLES
+The program below creates a thread and then cancels it.
+The main thread joins with the canceled thread to check
+that its exit status was
+.BR PTHREAD_CANCELED .
+The following shell session shows what happens when we run the program:
+.P
+.in +4n
+.EX
+$ ./a.out
+thread_func(): started; cancelation disabled
+main(): sending cancelation request
+thread_func(): about to enable cancelation
+main(): thread was canceled
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (pthread_cancel.c)
+.EX
+#include <errno.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+#define handle_error_en(en, msg) \e
+        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
+\&
+static void *
+thread_func(void *ignored_argument)
+{
+    int s;
+\&
+    /* Disable cancelation for a while, so that we don\[aq]t
+       immediately react to a cancelation request. */
+\&
+    s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
+    if (s != 0)
+        handle_error_en(s, "pthread_setcancelstate");
+\&
+    printf("%s(): started; cancelation disabled\en", __func__);
+    sleep(5);
+    printf("%s(): about to enable cancelation\en", __func__);
+\&
+    s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
+    if (s != 0)
+        handle_error_en(s, "pthread_setcancelstate");
+\&
+    /* sleep() is a cancelation point. */
+\&
+    sleep(1000);        /* Should get canceled while we sleep */
+\&
+    /* Should never get here. */
+\&
+    printf("%s(): not canceled!\en", __func__);
+    return NULL;
+}
+\&
+int
+main(void)
+{
+    pthread_t thr;
+    void *res;
+    int s;
+\&
+    /* Start a thread and then send it a cancelation request. */
+\&
+    s = pthread_create(&thr, NULL, &thread_func, NULL);
+    if (s != 0)
+        handle_error_en(s, "pthread_create");
+\&
+    sleep(2);           /* Give thread a chance to get started */
+\&
+    printf("%s(): sending cancelation request\en", __func__);
+    s = pthread_cancel(thr);
+    if (s != 0)
+        handle_error_en(s, "pthread_cancel");
+\&
+    /* Join with thread to see what its exit status was. */
+\&
+    s = pthread_join(thr, &res);
+    if (s != 0)
+        handle_error_en(s, "pthread_join");
+\&
+    if (res == PTHREAD_CANCELED)
+        printf("%s(): thread was canceled\en", __func__);
+    else
+        printf("%s(): thread wasn\[aq]t canceled (shouldn\[aq]t happen!)\en",
+               __func__);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR pthread_cleanup_push (3),
+.BR pthread_create (3),
+.BR pthread_exit (3),
+.BR pthread_join (3),
+.BR pthread_key_create (3),
+.BR pthread_setcancelstate (3),
+.BR pthread_setcanceltype (3),
+.BR pthread_testcancel (3),
+.BR pthreads (7)