From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/pthread_setcancelstate.3 | 201 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 man3/pthread_setcancelstate.3 (limited to 'man3/pthread_setcancelstate.3') diff --git a/man3/pthread_setcancelstate.3 b/man3/pthread_setcancelstate.3 new file mode 100644 index 0000000..5fd0d27 --- /dev/null +++ b/man3/pthread_setcancelstate.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setcancelstate 3 2023-07-30 "Linux man-pages 6.05.01" +.SH NAME +pthread_setcancelstate, pthread_setcanceltype \- +set cancelability state and type +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.PP +.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. +.PP +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.) +.PP +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 . +.PP +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 +.sp 1 +.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). +.PP +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. +.PP +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. +.PP +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) -- cgit v1.2.3