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