1PTHREAD_SETCANCELSTATE(P)  POSIX Programmer's Manual PTHREAD_SETCANCELSTATE(P)
2
3
4

NAME

6       pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel - set
7       cancelability state
8

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_setcancelstate(int state, int *oldstate);
13       int pthread_setcanceltype(int type, int *oldtype);
14       void pthread_testcancel(void);
15
16

DESCRIPTION

18       The pthread_setcancelstate() function shall  atomically  both  set  the
19       calling  thread's cancelability state to the indicated state and return
20       the previous cancelability state at the  location  referenced  by  old‐
21       state.   Legal   values   for   state   are  PTHREAD_CANCEL_ENABLE  and
22       PTHREAD_CANCEL_DISABLE.
23
24       The pthread_setcanceltype() function  shall  atomically  both  set  the
25       calling  thread's  cancelability  type to the indicated type and return
26       the previous cancelability type at the location referenced by  oldtype.
27       Legal  values  for  type  are  PTHREAD_CANCEL_DEFERRED and PTHREAD_CAN‐
28       CEL_ASYNCHRONOUS.
29
30       The cancelability state and type of any newly created threads,  includ‐
31       ing the thread in which main() was first invoked, shall be PTHREAD_CAN‐
32       CEL_ENABLE and PTHREAD_CANCEL_DEFERRED respectively.
33
34       The pthread_testcancel() function shall create a cancellation point  in
35       the  calling  thread.  The  pthread_testcancel() function shall have no
36       effect if cancelability is disabled.
37

RETURN VALUE

39       If successful, the pthread_setcancelstate() and pthread_setcanceltype()
40       functions  shall  return  zero;  otherwise,  an  error  number shall be
41       returned to indicate the error.
42

ERRORS

44       The pthread_setcancelstate() function may fail if:
45
46       EINVAL The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CAN‐
47              CEL_DISABLE.
48
49
50       The pthread_setcanceltype() function may fail if:
51
52       EINVAL The   specified   type   is   not   PTHREAD_CANCEL_DEFERRED   or
53              PTHREAD_CANCEL_ASYNCHRONOUS.
54
55
56       These functions shall not return an error code of [EINTR].
57
58       The following sections are informative.
59

EXAMPLES

61       None.
62

APPLICATION USAGE

64       None.
65

RATIONALE

67       The pthread_setcancelstate() and pthread_setcanceltype() functions con‐
68       trol  the  points at which a thread may be asynchronously canceled. For
69       cancellation control to be usable in modular fashion, some  rules  need
70       to be followed.
71
72       An  object can be considered to be a generalization of a procedure.  It
73       is a set of procedures and global  variables  written  as  a  unit  and
74       called  by clients not known by the object. Objects may depend on other
75       objects.
76
77       First, cancelability should only be disabled on  entry  to  an  object,
78       never  explicitly  enabled.  On  exit from an object, the cancelability
79       state should always be restored to its value on entry to the object.
80
81       This follows from a modularity argument: if the client of an object (or
82       the client of an object that uses that object) has disabled cancelabil‐
83       ity, it is because the client does  not  want  to  be  concerned  about
84       cleaning  up if the thread is canceled while executing some sequence of
85       actions. If an object is called in such a state and it enables cancela‐
86       bility  and a cancellation request is pending for that thread, then the
87       thread is canceled, contrary to the wish of the client that disabled.
88
89       Second, the cancelability type may be explicitly set to either deferred
90       or asynchronous upon entry to an object.  But as with the cancelability
91       state, on exit from an object the cancelability type should  always  be
92       restored to its value on entry to the object.
93
94       Finally,  only  functions  that  are  cancel-safe  may be called from a
95       thread that is asynchronously cancelable.
96

FUTURE DIRECTIONS

98       None.
99

SEE ALSO

101       pthread_cancel() , the Base Definitions volume of IEEE Std 1003.1-2001,
102       <pthread.h>
103

105       Portions  of  this text are reprinted and reproduced in electronic form
106       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
107       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
108       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
109       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
110       event of any discrepancy between this version and the original IEEE and
111       The  Open Group Standard, the original IEEE and The Open Group Standard
112       is the referee document. The original Standard can be  obtained  online
113       at http://www.opengroup.org/unix/online.html .
114
115
116
117IEEE/The Open Group                  2003            PTHREAD_SETCANCELSTATE(P)
Impressum