diff options
Diffstat (limited to 'man3/pthread_setcancelstate.3')
-rw-r--r-- | man3/pthread_setcancelstate.3 | 200 |
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) |