Merging upstream version 6.8.

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

1 files changed, 200 insertions, 0 deletions

diff --git a/man/man3/pthread_setcancelstate.3 b/man/man3/pthread_setcancelstate.3
new file mode 100644
index 0000000..6b65f0f
--- /dev/null
+++ b/man/man3/pthread_setcancelstate.3
@@ -0,0 +1,200 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\"     <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_setcancelstate 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+pthread_setcancelstate, pthread_setcanceltype \-
+set cancelability state and type
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.P
+.BI "int pthread_setcancelstate(int " state ", int *" oldstate );
+.BI "int pthread_setcanceltype(int " type ", int *" oldtype );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_setcancelstate ()
+sets the cancelability state of the calling thread to the value
+given in
+.IR state .
+The previous cancelability state of the thread is returned
+in the buffer pointed to by
+.IR oldstate .
+The
+.I state
+argument must have one of the following values:
+.TP
+.B PTHREAD_CANCEL_ENABLE
+The thread is cancelable.
+This is the default cancelability state in all new threads,
+including the initial thread.
+The thread's cancelability type determines when a cancelable thread
+will respond to a cancelation request.
+.TP
+.B PTHREAD_CANCEL_DISABLE
+The thread is not cancelable.
+If a cancelation request is received,
+it is blocked until cancelability is enabled.
+.P
+The
+.BR pthread_setcanceltype ()
+sets the cancelability type of the calling thread to the value
+given in
+.IR type .
+The previous cancelability type of the thread is returned
+in the buffer pointed to by
+.IR oldtype .
+The
+.I type
+argument must have one of the following values:
+.TP
+.B PTHREAD_CANCEL_DEFERRED
+A cancelation request is deferred until the thread next calls
+a function that is a cancelation point (see
+.BR pthreads (7)).
+This is the default cancelability type in all new threads,
+including the initial thread.
+.IP
+Even with deferred cancelation, a
+cancelation point in an asynchronous signal handler may still
+be acted upon and the effect is as if it was an asynchronous
+cancelation.
+.TP
+.B PTHREAD_CANCEL_ASYNCHRONOUS
+The thread can be canceled at any time.
+(Typically,
+it will be canceled immediately upon receiving a cancelation request,
+but the system doesn't guarantee this.)
+.P
+The set-and-get operation performed by each of these functions
+is atomic with respect to other threads in the process
+calling the same function.
+.SH RETURN VALUE
+On success, these functions return 0;
+on error, they return a nonzero error number.
+.SH ERRORS
+The
+.BR pthread_setcancelstate ()
+can fail with the following error:
+.TP
+.B EINVAL
+Invalid value for
+.IR state .
+.P
+The
+.BR pthread_setcanceltype ()
+can fail with the following error:
+.TP
+.B EINVAL
+Invalid value for
+.IR type .
+.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_setcancelstate (),
+.BR pthread_setcanceltype ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Safe
+T}
+T{
+.na
+.nh
+.BR pthread_setcancelstate (),
+.BR pthread_setcanceltype ()
+T}	Async-cancel safety	T{
+.na
+.nh
+AC-Safe
+T}
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.0
+POSIX.1-2001.
+.SH NOTES
+For details of what happens when a thread is canceled, see
+.BR \%pthread_cancel (3).
+.P
+Briefly disabling cancelability is useful
+if a thread performs some critical action
+that must not be interrupted by a cancelation request.
+Beware of disabling cancelability for long periods,
+or around operations that may block for long periods,
+since that will render the thread unresponsive to cancelation requests.
+.SS Asynchronous cancelability
+Setting the cancelability type to
+.B PTHREAD_CANCEL_ASYNCHRONOUS
+is rarely useful.
+Since the thread could be canceled at
+.I any
+time, it cannot safely reserve resources (e.g., allocating memory with
+.BR malloc (3)),
+acquire mutexes, semaphores, or locks, and so on.
+Reserving resources is unsafe because the application has no way of
+knowing what the state of these resources is when the thread is canceled;
+that is, did cancelation occur before the resources were reserved,
+while they were reserved, or after they were released?
+Furthermore, some internal data structures
+(e.g., the linked list of free blocks managed by the
+.BR malloc (3)
+family of functions) may be left in an inconsistent state
+if cancelation occurs in the middle of the function call.
+Consequently, clean-up handlers cease to be useful.
+.P
+Functions that can be safely asynchronously canceled are called
+.IR "async-cancel-safe functions" .
+POSIX.1-2001 and POSIX.1-2008 require only that
+.BR pthread_cancel (3),
+.BR pthread_setcancelstate (),
+and
+.BR pthread_setcanceltype ()
+be async-cancel-safe.
+In general, other library functions
+can't be safely called from an asynchronously cancelable thread.
+.P
+One of the few circumstances in which asynchronous cancelability is useful
+is for cancelation of a thread that is in a pure compute-bound loop.
+.SS Portability notes
+The Linux threading implementations permit the
+.I oldstate
+argument of
+.BR pthread_setcancelstate ()
+to be NULL, in which case the information about the previous
+cancelability state is not returned to the caller.
+Many other implementations also permit a NULL
+.I oldstat
+argument,
+.\" It looks like at least Solaris, FreeBSD and Tru64 support this.
+but POSIX.1 does not specify this point,
+so portable applications should always specify a non-NULL value in
+.IR oldstate .
+A precisely analogous set of statements applies for the
+.I oldtype
+argument of
+.BR pthread_setcanceltype ().
+.SH EXAMPLES
+See
+.BR pthread_cancel (3).
+.SH SEE ALSO
+.BR pthread_cancel (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_testcancel (3),
+.BR pthreads (7)