summaryrefslogtreecommitdiffstats
path: root/man3/pthread_setcancelstate.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/pthread_setcancelstate.3')
-rw-r--r--man3/pthread_setcancelstate.3200
1 files changed, 0 insertions, 200 deletions
diff --git a/man3/pthread_setcancelstate.3 b/man3/pthread_setcancelstate.3
deleted file mode 100644
index 40b0a6e..0000000
--- a/man3/pthread_setcancelstate.3
+++ /dev/null
@@ -1,200 +0,0 @@
-'\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)