3 .Dt PTHREAD_TESTCANCEL 3
6 .Nm pthread_setcancelstate ,
7 .Nm pthread_setcanceltype ,
9 .Nd set cancelability state
15 .Fn pthread_setcancelstate "int state" "int *oldstate"
17 .Fn pthread_setcanceltype "int type" "int *oldtype"
19 .Fn pthread_testcancel "void"
22 .Fn pthread_setcancelstate
23 function atomically both sets the calling thread's cancelability state
30 returns the previous cancelability state at the location referenced by
35 .Dv PTHREAD_CANCEL_ENABLE
37 .Dv PTHREAD_CANCEL_DISABLE .
40 .Fn pthread_setcanceltype
41 function atomically both sets the calling thread's cancelability type
48 returns the previous cancelability type at the location referenced by
53 .Dv PTHREAD_CANCEL_DEFERRED
55 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
57 The cancelability state and type of any newly created threads, including the
60 was first invoked, are
61 .Dv PTHREAD_CANCEL_ENABLE
63 .Dv PTHREAD_CANCEL_DEFERRED
67 .Fn pthread_testcancel
68 function creates a cancellation point in the calling thread.
70 .Fn pthread_testcancel
71 function has no effect if cancelability is disabled.
73 .Ss Cancelability States
74 The cancelability state of a thread determines the action taken upon
75 receipt of a cancellation request.
76 The thread may control cancellation in
79 Each thread maintains its own
80 .Dq cancelability state
81 which may be encoded in two bits:
83 .It Em Cancelability Enable
85 .Dv PTHREAD_CANCEL_DISABLE ,
86 cancellation requests against the target thread are held pending.
87 .It Em Cancelability Type
88 When cancelability is enabled and the cancelability type is
89 .Dv PTHREAD_CANCEL_ASYNCHRONOUS ,
90 new or pending cancellation requests may be acted upon at any time.
91 When cancelability is enabled and the cancelability type is
92 .Dv PTHREAD_CANCEL_DEFERRED ,
93 cancellation requests are held pending until a cancellation point (see
95 If cancelability is disabled, the setting of the
96 cancelability type has no immediate effect as all cancellation requests
97 are held pending; however, once cancelability is enabled again the new
98 type will be in effect.
100 .Ss Cancellation Points
101 Cancellation points will occur when a thread is executing the following
103 .Bl -tag -width "Fn pthread_cond_timedwait" -compact
108 .It Fn clock_nanosleep
114 function is a cancellation point if
123 function is a cancellation point if it is potentially blocking,
126 argument is non-zero.
129 .It Fn mq_timedreceive
139 .It Fn pthread_cond_timedwait
140 .It Fn pthread_cond_wait
142 .It Fn pthread_testcancel
150 .It Fn sem_clockwait_np
174 .Fn pthread_setcancelstate
176 .Fn pthread_setcanceltype
177 functions are used to control the points at which a thread may be
178 asynchronously canceled.
179 For cancellation control to be usable in modular
180 fashion, some rules must be followed.
182 For purposes of this discussion, consider an object to be a generalization
184 It is a set of procedures and global variables written as
185 a unit and called by clients not known by the object.
189 First, cancelability should only be disabled on entry to an object, never
191 On exit from an object, the cancelability state should
192 always be restored to its value on entry to the object.
194 This follows from a modularity argument: if the client of an object (or the
195 client of an object that uses that object) has disabled cancelability, it is
196 because the client does not want to have to worry about how to clean up if the
197 thread is canceled while executing some sequence of actions.
199 is called in such a state and it enables cancelability and a cancellation
200 request is pending for that thread, then the thread will be canceled,
201 contrary to the wish of the client that disabled.
203 Second, the cancelability type may be explicitly set to either
207 upon entry to an object.
208 But as with the cancelability state, on exit from
209 an object that cancelability type should always be restored to its value on
212 Finally, only functions that are cancel-safe may be called from a thread that
213 is asynchronously cancelable.
216 .Fn pthread_setcancelstate
218 .Fn pthread_setcanceltype
219 functions will return zero.
220 Otherwise, an error number shall be returned to
224 .Fn pthread_setcancelstate
228 The specified state is not
229 .Dv PTHREAD_CANCEL_ENABLE
231 .Dv PTHREAD_CANCEL_DISABLE .
235 .Fn pthread_setcanceltype
239 The specified state is not
240 .Dv PTHREAD_CANCEL_DEFERRED
242 .Dv PTHREAD_CANCEL_ASYNCHRONOUS .
248 .Fn pthread_testcancel
251 The standard allows implementations to make many more functions
254 This manual page was written by
255 .An David Leonard Aq Mt d@openbsd.org
259 .Xr pthread_cancel 3 .