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