1PTHREAD_SETCANCELSTATE(3)  Linux Programmer's Manual PTHREAD_SETCANCELSTATE(3)
2
3
4

NAME

6       pthread_setcancelstate, pthread_setcanceltype - set cancelability state
7       and type
8

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_setcancelstate(int state, int *oldstate);
13       int pthread_setcanceltype(int type, int *oldtype);
14
15       Compile and link with -pthread.
16

DESCRIPTION

18       The pthread_setcancelstate() sets the cancelability state of the  call‐
19       ing  thread  to  the  value given in state.  The previous cancelability
20       state of the thread is returned in the buffer pointed to  by  oldstate.
21       The state argument must have one of the following values:
22
23       PTHREAD_CANCEL_ENABLE
24              The  thread  is  cancelable.   This is the default cancelability
25              state in all new threads, including  the  initial  thread.   The
26              thread's  cancelability type determines when a cancelable thread
27              will respond to a cancellation request.
28
29       PTHREAD_CANCEL_DISABLE
30              The thread is not cancelable.  If a cancellation request is  re‐
31              ceived, it is blocked until cancelability is enabled.
32
33       The  pthread_setcanceltype() sets the cancelability type of the calling
34       thread to the value given in type.  The previous cancelability type  of
35       the  thread  is returned in the buffer pointed to by oldtype.  The type
36       argument must have one of the following values:
37
38       PTHREAD_CANCEL_DEFERRED
39              A cancellation request is deferred until the thread next calls a
40              function  that  is a cancellation point (see pthreads(7)).  This
41              is the default cancelability type in all new threads,  including
42              the initial thread.
43
44              Even  with  deferred  cancellation,  a  cancellation point in an
45              asynchronous signal handler may still be acted upon and the  ef‐
46              fect is as if it was an asynchronous cancellation.
47
48       PTHREAD_CANCEL_ASYNCHRONOUS
49              The  thread can be canceled at any time.  (Typically, it will be
50              canceled immediately upon receiving a cancellation request,  but
51              the system doesn't guarantee this.)
52
53       The  set-and-get  operation  performed  by  each  of these functions is
54       atomic with respect to other threads in the process  calling  the  same
55       function.
56

RETURN VALUE

58       On  success,  these functions return 0; on error, they return a nonzero
59       error number.
60

ERRORS

62       The pthread_setcancelstate() can fail with the following error:
63
64       EINVAL Invalid value for state.
65
66       The pthread_setcanceltype() can fail with the following error:
67
68       EINVAL Invalid value for type.
69

ATTRIBUTES

71       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
72       tributes(7).
73
74       ┌──────────────────────────┬─────────────────────┬─────────┐
75Interface                 Attribute           Value   
76       ├──────────────────────────┼─────────────────────┼─────────┤
77pthread_setcancelstate(), │ Thread safety       │ MT-Safe │
78pthread_setcanceltype()   │                     │         │
79       ├──────────────────────────┼─────────────────────┼─────────┤
80pthread_setcancelstate(), │ Async-cancel-safety │ AC-Safe │
81pthread_setcanceltype()   │                     │         │
82       └──────────────────────────┴─────────────────────┴─────────┘

CONFORMING TO

84       POSIX.1-2001, POSIX.1-2008.
85

NOTES

87       For details of what happens when a thread is canceled, see pthread_can‐
88       cel(3).
89
90       Briefly disabling cancelability is useful if  a  thread  performs  some
91       critical action that must not be interrupted by a cancellation request.
92       Beware of disabling cancelability for long periods,  or  around  opera‐
93       tions  that  may  block  for  long  periods, since that will render the
94       thread unresponsive to cancellation requests.
95
96   Asynchronous cancelability
97       Setting the cancelability type to PTHREAD_CANCEL_ASYNCHRONOUS is rarely
98       useful.   Since  the  thread  could  be canceled at any time, it cannot
99       safely reserve resources (e.g., allocating memory with malloc(3)),  ac‐
100       quire mutexes, semaphores, or locks, and so on.  Reserving resources is
101       unsafe because the application has no way of knowing what the state  of
102       these  resources is when the thread is canceled; that is, did cancella‐
103       tion occur before the resources were  reserved,  while  they  were  re‐
104       served,  or  after they were released?  Furthermore, some internal data
105       structures (e.g., the linked list of free blocks managed  by  the  mal‐
106       loc(3)  family  of  functions)  may be left in an inconsistent state if
107       cancellation occurs in the middle of the function call.   Consequently,
108       clean-up handlers cease to be useful.
109
110       Functions  that can be safely asynchronously canceled are called async-
111       cancel-safe functions.  POSIX.1-2001 and POSIX.1-2008 require only that
112       pthread_cancel(3),   pthread_setcancelstate(),  and  pthread_setcancel‐
113       type() be async-cancel-safe.  In general, other library functions can't
114       be safely called from an asynchronously cancelable thread.
115
116       One  of  the  few  circumstances in which asynchronous cancelability is
117       useful is for cancellation of a thread that is in a pure  compute-bound
118       loop.
119
120   Portability notes
121       The  Linux  threading  implementations  permit the oldstate argument of
122       pthread_setcancelstate() to be NULL,  in  which  case  the  information
123       about  the  previous cancelability state is not returned to the caller.
124       Many other implementations also permit a  NULL  oldstat  argument,  but
125       POSIX.1  does  not  specify this point, so portable applications should
126       always specify a non-NULL value in oldstate.  A precisely analogous set
127       of  statements  applies  for the oldtype argument of pthread_setcancel‐
128       type().
129

EXAMPLES

131       See pthread_cancel(3).
132

SEE ALSO

134       pthread_cancel(3),   pthread_cleanup_push(3),    pthread_testcancel(3),
135       pthreads(7)
136

COLOPHON

138       This  page  is  part of release 5.10 of the Linux man-pages project.  A
139       description of the project, information about reporting bugs,  and  the
140       latest     version     of     this    page,    can    be    found    at
141       https://www.kernel.org/doc/man-pages/.
142
143
144
145Linux                             2020-06-09         PTHREAD_SETCANCELSTATE(3)
Impressum