1.\" $OpenBSD: pthread_testcancel.3,v 1.11 2007/05/31 19:19:37 jmc Exp $
2.\"
3.\"
4.\"  David Leonard, 1999. Public Domain.
5.\"
6.Dd $Mdocdate: May 31 2007 $
7.Dt PTHREAD_TESTCANCEL 3
8.Os
9.Sh NAME
10.Nm pthread_setcancelstate ,
11.Nm pthread_setcanceltype ,
12.Nm pthread_testcancel
13.Nd set cancelability state
14.Sh SYNOPSIS
15.Fd #include <pthread.h>
16.Ft int
17.Fn pthread_setcancelstate "int state" "int *oldstate"
18.Ft int
19.Fn pthread_setcanceltype "int type" "int *oldtype"
20.Ft void
21.Fn pthread_testcancel "void"
22.Sh DESCRIPTION
23The
24.Fn pthread_setcancelstate
25function atomically both sets the calling thread's cancelability state
26to the indicated
27.Fa state
28and, if
29.Fa oldstate
30is not
31.Dv NULL ,
32returns the previous cancelability state at the location referenced by
33.Fa oldstate .
34Legal values for
35.Fa state
36are
37.Dv PTHREAD_CANCEL_ENABLE
38and
39.Dv PTHREAD_CANCEL_DISABLE .
40.Pp
41The
42.Fn pthread_setcanceltype
43function atomically both sets the calling thread's cancelability type
44to the indicated
45.Fa type
46and, if
47.Fa oldtype
48is not
49.Dv NULL ,
50returns the previous cancelability type at the location referenced by
51.Fa oldtype .
52Legal values for
53.Fa type
54are
55.Dv PTHREAD_CANCEL_DEFERRED
56and
57.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
58.Pp
59The cancelability state and type of any newly created threads, including the
60thread in which
61.Fn main
62was first invoked, are
63.Dv PTHREAD_CANCEL_ENABLE
64and
65.Dv PTHREAD_CANCEL_DEFERRED
66respectively.
67.Pp
68The
69.Fn pthread_testcancel
70function creates a cancellation point in the calling thread.
71The
72.Fn pthread_testcancel
73function has no effect if cancelability is disabled.
74.Ss Cancelability States
75The cancelability state of a thread determines the action taken upon
76receipt of a cancellation request.
77The thread may control cancellation in a number of ways.
78.Pp
79Each thread maintains its own
80.Dq cancelability state
81which may be encoded in two bits:
82.Bl -hang
83.It Em Cancelability Enable
84When cancelability is
85.Dv PTHREAD_CANCEL_DISABLE ,
86cancellation requests against the target thread are held pending.
87.It Em Cancelability Type
88When cancelability is enabled and the cancelability type is
89.Dv PTHREAD_CANCEL_ASYNCHRONOUS ,
90new or pending cancellation requests may be acted upon at any time.
91When cancelability is enabled and the cancelability type is
92.Dv PTHREAD_CANCEL_DEFERRED ,
93cancellation requests are held pending until a cancellation point (see
94below) is reached.
95If cancelability is disabled, the setting of the
96cancelability type has no immediate effect as all cancellation requests
97are held pending; however, once cancelability is enabled again the new
98type will be in effect.
99.El
100.Ss Cancellation Points
101Cancellation points will occur when a thread is executing the following
102functions:
103.Fn close ,
104.Fn creat ,
105.Fn fcntl ,
106.Fn fsync ,
107.Fn msync ,
108.Fn nanosleep ,
109.Fn open ,
110.Fn pause ,
111.Fn pthread_cond_timedwait ,
112.Fn pthread_cond_wait ,
113.Fn pthread_join ,
114.Fn pthread_testcancel ,
115.Fn read ,
116.Fn sigwaitinfo ,
117.Fn sigsuspend ,
118.Fn sigwait ,
119.Fn sleep ,
120.Fn system ,
121.Fn tcdrain ,
122.Fn wait ,
123.Fn waitpid ,
124.Fn write .
125.Sh RETURN VALUES
126If successful, the
127.Fn pthread_setcancelstate
128and
129.Fn pthread_setcanceltype
130functions will return zero.
131Otherwise, an error number shall be returned to indicate the error.
132.Pp
133The
134.Fn pthread_setcancelstate
135and
136.Fn pthread_setcanceltype
137functions are used to control the points at which a thread may be
138asynchronously cancelled.
139For cancellation control to be usable in modular
140fashion, some rules must be followed.
141.Pp
142For purposes of this discussion, consider an object to be a generalization
143of a procedure. It is a set of procedures and global variables written as
144a unit and called by clients not known by the object.
145Objects may depend on other objects.
146.Pp
147First, cancelability should only be disabled on entry to an object, never
148explicitly enabled.
149On exit from an object, the cancelability state should
150always be restored to its value on entry to the object.
151.Pp
152This follows from a modularity argument: if the client of an object (or the
153client of an object that uses that object) has disabled cancelability, it is
154because the client doesn't want to have to worry about how to clean up if the
155thread is cancelled while executing some sequence of actions.
156If an object
157is called in such a state and it enables cancelability and a cancellation
158request is pending for that thread, then the thread will be cancelled,
159contrary to the wish of the client that disabled.
160.Pp
161Second, the cancelability type may be explicitly set to either
162.Em deferred
163or
164.Em asynchronous
165upon entry to an object.
166But as with the cancelability state, on exit from
167an object that cancelability type should always be restored to its value on
168entry to the object.
169.Pp
170Finally, only functions that are cancel-safe may be called from a thread that
171is asynchronously cancelable.
172.Sh ERRORS
173The function
174.Fn pthread_setcancelstate
175may fail with:
176.Bl -tag -width Er
177.It Bq Er EINVAL
178The specified state is not
179.Dv PTHREAD_CANCEL_ENABLE
180or
181.Dv PTHREAD_CANCEL_DISABLE .
182.El
183.Pp
184The function
185.Fn pthread_setcanceltype
186may fail with:
187.Bl -tag -width Er
188.It Bq Er EINVAL
189The specified state is not
190.Dv PTHREAD_CANCEL_DEFERRED
191or
192.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
193.El
194.Sh SEE ALSO
195.Xr pthread_cancel 3
196.Sh STANDARDS
197.Fn pthread_testcancel
198conforms to
199.St -p1003.1-96
200