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
31              received, 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       PTHREAD_CANCEL_ASYNCHRONOUS
45              The  thread can be canceled at any time.  (Typically, it will be
46              canceled immediately upon receiving a cancellation request,  but
47              the system doesn't guarantee this.)
48
49       The  set-and-get  operation  performed  by  each  of these functions is
50       atomic with respect to other threads in the process  calling  the  same
51       function.
52

RETURN VALUE

54       On  success,  these functions return 0; on error, they return a nonzero
55       error number.
56

ERRORS

58       The pthread_setcancelstate() can fail with the following error:
59
60       EINVAL Invalid value for state.
61
62       The pthread_setcanceltype() can fail with the following error:
63
64       EINVAL Invalid value for type.
65

CONFORMING TO

67       POSIX.1-2001.
68

NOTES

70       For details of what happens when a thread is canceled, see pthread_can‐
71       cel(3).
72
73       Briefly  disabling  cancelability  is  useful if a thread performs some
74       critical action that must not be interrupted by a cancellation request.
75       Beware  of  disabling  cancelability for long periods, or around opera‐
76       tions that may block for long  periods,  since  that  will  render  the
77       thread unresponsive to cancellation requests.
78
79       Setting the cancelability type to PTHREAD_CANCEL_ASYNCHRONOUS is rarely
80       useful.  Since the thread could be canceled  at  any  time,  it  cannot
81       safely  reserve  resources  (e.g.,  allocating  memory with malloc(3)),
82       acquire mutexes, semaphores, or locks, and so on.  Reserving  resources
83       is  unsafe because the application has no way of knowing what the state
84       of these resources is when the thread is canceled; that is, did cancel‐
85       lation  occur  before  the  resources  were  reserved,  while they were
86       reserved, or after they were released?  Furthermore, some internal data
87       structures  (e.g.,  the  linked list of free blocks managed by the mal‐
88       loc(3) family of functions) may be left in  an  inconsistent  state  if
89       cancellation  occurs in the middle of the function call.  Consequently,
90       clean-up handlers cease to be useful.  Functions  that  can  be  safely
91       asynchronously   canceled   are   called  async-cancel-safe  functions.
92       POSIX.1-2001 only requires that  pthread_cancel(3),  pthread_setcancel‐
93       state(), and pthread_setcanceltype() be async-cancel-safe.  In general,
94       other library functions can't be safely called from  an  asynchronously
95       cancelable  thread.  One of the few circumstances in which asynchronous
96       cancelability is useful is for cancellation of a thread that  is  in  a
97       pure compute-bound loop.
98
99       The  Linux  threading  implementations  permit the oldstate argument of
100       pthread_setcancelstate() to be NULL,  in  which  case  the  information
101       about  the  previous cancelability state is not returned to the caller.
102       Many other implementations also permit a  NULL  oldstat  argument,  but
103       POSIX.1-2001  does  not  specify  this  point, so portable applications
104       should always specify a non-NULL value in oldstate.  A precisely analo‐
105       gous set of statements applies for the oldtype argument of pthread_set‐
106       canceltype().
107

EXAMPLE

109       See pthread_cancel(3).
110

SEE ALSO

112       pthread_cleanup_push(3),   pthread_cancel(3),    pthread_testcancel(3),
113       pthreads(7)
114

COLOPHON

116       This  page  is  part of release 3.25 of the Linux man-pages project.  A
117       description of the project, and information about reporting  bugs,  can
118       be found at http://www.kernel.org/doc/man-pages/.
119
120
121
122Linux                             2008-11-24         PTHREAD_SETCANCELSTATE(3)
Impressum