xref: /freebsd/share/man/man3/pthread_testcancel.3 (revision edf8578117e8844e02c0121147f45e4609b30680)
1.Dd March 18, 2017
2.Dt PTHREAD_TESTCANCEL 3
3.Os
4.Sh NAME
5.Nm pthread_setcancelstate ,
6.Nm pthread_setcanceltype ,
7.Nm pthread_testcancel
8.Nd set cancelability state
9.Sh LIBRARY
10.Lb libpthread
11.Sh SYNOPSIS
12.In pthread.h
13.Ft int
14.Fn pthread_setcancelstate "int state" "int *oldstate"
15.Ft int
16.Fn pthread_setcanceltype "int type" "int *oldtype"
17.Ft void
18.Fn pthread_testcancel "void"
19.Sh DESCRIPTION
20The
21.Fn pthread_setcancelstate
22function atomically both sets the calling thread's cancelability state
23to the indicated
24.Fa state
25and, if
26.Fa oldstate
27is not
28.Dv NULL ,
29returns the previous cancelability state at the location referenced by
30.Fa oldstate .
31Legal values for
32.Fa state
33are
34.Dv PTHREAD_CANCEL_ENABLE
35and
36.Dv PTHREAD_CANCEL_DISABLE .
37.Pp
38The
39.Fn pthread_setcanceltype
40function atomically both sets the calling thread's cancelability type
41to the indicated
42.Fa type
43and, if
44.Fa oldtype
45is not
46.Dv NULL ,
47returns the previous cancelability type at the location referenced by
48.Fa oldtype .
49Legal values for
50.Fa type
51are
52.Dv PTHREAD_CANCEL_DEFERRED
53and
54.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
55.Pp
56The cancelability state and type of any newly created threads, including the
57thread in which
58.Fn main
59was first invoked, are
60.Dv PTHREAD_CANCEL_ENABLE
61and
62.Dv PTHREAD_CANCEL_DEFERRED
63respectively.
64.Pp
65The
66.Fn pthread_testcancel
67function creates a cancellation point in the calling thread.
68The
69.Fn pthread_testcancel
70function has no effect if cancelability is disabled.
71.Ss Cancelability States
72The cancelability state of a thread determines the action taken upon
73receipt of a cancellation request.
74The thread may control cancellation in
75a number of ways.
76.Pp
77Each thread maintains its own
78.Dq cancelability state
79which may be encoded in two bits:
80.Bl -hang
81.It Em Cancelability Enable
82When cancelability is
83.Dv PTHREAD_CANCEL_DISABLE ,
84cancellation requests against the target thread are held pending.
85.It Em Cancelability Type
86When cancelability is enabled and the cancelability type is
87.Dv PTHREAD_CANCEL_ASYNCHRONOUS ,
88new or pending cancellation requests may be acted upon at any time.
89When cancelability is enabled and the cancelability type is
90.Dv PTHREAD_CANCEL_DEFERRED ,
91cancellation requests are held pending until a cancellation point (see
92below) is reached.
93If cancelability is disabled, the setting of the
94cancelability type has no immediate effect as all cancellation requests
95are held pending; however, once cancelability is enabled again the new
96type will be in effect.
97.El
98.Ss Cancellation Points
99Cancellation points will occur when a thread is executing the following
100functions:
101.Bl -tag -width "Fn pthread_cond_timedwait" -compact
102.It Fn accept
103.It Fn accept4
104.It Fn aio_suspend
105.It Fn connect
106.It Fn clock_nanosleep
107.It Fn close
108.It Fn creat
109.It Fn fcntl
110The
111.Fn fcntl
112function is a cancellation point if
113.Fa cmd
114is
115.Dv F_SETLKW .
116.It Fn fdatasync
117.It Fn fsync
118.It Fn kevent
119The
120.Fn kevent
121function is a cancellation point if it is potentially blocking,
122such as when the
123.Fa nevents
124argument is non-zero.
125.It Fn mq_receive
126.It Fn mq_send
127.It Fn mq_timedreceive
128.It Fn mq_timedsend
129.It Fn msync
130.It Fn nanosleep
131.It Fn open
132.It Fn openat
133.It Fn pause
134.It Fn poll
135.It Fn ppoll
136.It Fn pselect
137.It Fn pthread_cond_timedwait
138.It Fn pthread_cond_wait
139.It Fn pthread_join
140.It Fn pthread_testcancel
141.It Fn read
142.It Fn readv
143.It Fn recv
144.It Fn recvfrom
145.It Fn recvmsg
146.It Fn select
147.It Fn sem_timedwait
148.It Fn sem_clockwait_np
149.It Fn sem_wait
150.It Fn send
151.It Fn sendmsg
152.It Fn sendto
153.It Fn sigsuspend
154.It Fn sigtimedwait
155.It Fn sigwaitinfo
156.It Fn sigwait
157.It Fn sleep
158.It Fn system
159.It Fn tcdrain
160.It Fn usleep
161.It Fn wait
162.It Fn wait3
163.It Fn wait4
164.It Fn wait6
165.It Fn waitid
166.It Fn waitpid
167.It Fn write
168.It Fn writev
169.El
170.Sh NOTES
171The
172.Fn pthread_setcancelstate
173and
174.Fn pthread_setcanceltype
175functions are used to control the points at which a thread may be
176asynchronously canceled.
177For cancellation control to be usable in modular
178fashion, some rules must be followed.
179.Pp
180For purposes of this discussion, consider an object to be a generalization
181of a procedure.
182It is a set of procedures and global variables written as
183a unit and called by clients not known by the object.
184Objects may depend
185on other objects.
186.Pp
187First, cancelability should only be disabled on entry to an object, never
188explicitly enabled.
189On exit from an object, the cancelability state should
190always be restored to its value on entry to the object.
191.Pp
192This follows from a modularity argument: if the client of an object (or the
193client of an object that uses that object) has disabled cancelability, it is
194because the client does not want to have to worry about how to clean up if the
195thread is canceled while executing some sequence of actions.
196If an object
197is called in such a state and it enables cancelability and a cancellation
198request is pending for that thread, then the thread will be canceled,
199contrary to the wish of the client that disabled.
200.Pp
201Second, the cancelability type may be explicitly set to either
202.Em deferred
203or
204.Em asynchronous
205upon entry to an object.
206But as with the cancelability state, on exit from
207an object that cancelability type should always be restored to its value on
208entry to the object.
209.Pp
210Finally, only functions that are cancel-safe may be called from a thread that
211is asynchronously cancelable.
212.Sh RETURN VALUES
213If successful, the
214.Fn pthread_setcancelstate
215and
216.Fn pthread_setcanceltype
217functions will return zero.
218Otherwise, an error number shall be returned to
219indicate the error.
220.Sh ERRORS
221The function
222.Fn pthread_setcancelstate
223may fail with:
224.Bl -tag -width Er
225.It Bq Er EINVAL
226The specified state is not
227.Dv PTHREAD_CANCEL_ENABLE
228or
229.Dv PTHREAD_CANCEL_DISABLE .
230.El
231.Pp
232The function
233.Fn pthread_setcanceltype
234may fail with:
235.Bl -tag -width Er
236.It Bq Er EINVAL
237The specified state is not
238.Dv PTHREAD_CANCEL_DEFERRED
239or
240.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
241.El
242.Sh SEE ALSO
243.Xr pthread_cancel 3
244.Sh STANDARDS
245The
246.Fn pthread_testcancel
247function conforms to
248.St -p1003.1-96 .
249The standard allows implementations to make many more functions
250cancellation points.
251.Sh AUTHORS
252This manual page was written by
253.An David Leonard Aq Mt d@openbsd.org
254for the
255.Ox
256implementation of
257.Xr pthread_cancel 3 .
258