Merge remote branch 'crater/vendor/MDOCML' into HEAD
[dragonfly.git] / lib / libpthread / pthread_testcancel.3
CommitLineData
15acf97d 1.\" $FreeBSD: src/share/man/man3/pthread_testcancel.3,v 1.15 2007/10/22 10:08:01 ru Exp $
c2cd059b 2.\" $DragonFly: src/lib/libc_r/man/pthread_testcancel.3,v 1.3 2006/03/26 22:56:56 swildner Exp $
15acf97d 3.Dd July 10, 2009
984263bc
MD
4.Dt PTHREAD_TESTCANCEL 3
5.Os
6.Sh NAME
7.Nm pthread_setcancelstate ,
8.Nm pthread_setcanceltype ,
9.Nm pthread_testcancel
10.Nd set cancelability state
11.Sh LIBRARY
9964d5ef 12.Lb libpthread
984263bc
MD
13.Sh SYNOPSIS
14.In pthread.h
15.Ft int
16.Fn pthread_setcancelstate "int state" "int *oldstate"
17.Ft int
18.Fn pthread_setcanceltype "int type" "int *oldtype"
19.Ft void
20.Fn pthread_testcancel "void"
21.Sh DESCRIPTION
22The
23.Fn pthread_setcancelstate
24function atomically both sets the calling thread's cancelability state
25to the indicated
26.Fa state
27and, if
28.Fa oldstate
29is not
30.Dv NULL ,
31returns the previous cancelability state at the location referenced by
32.Fa oldstate .
33Legal values for
34.Fa state
35are
36.Dv PTHREAD_CANCEL_ENABLE
37and
38.Dv PTHREAD_CANCEL_DISABLE .
39.Pp
40The
41.Fn pthread_setcanceltype
42function atomically both sets the calling thread's cancelability type
43to the indicated
44.Fa type
45and, if
46.Fa oldtype
47is not
48.Dv NULL ,
49returns the previous cancelability type at the location referenced by
50.Fa oldtype .
51Legal values for
52.Fa type
53are
54.Dv PTHREAD_CANCEL_DEFERRED
55and
56.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
57.Pp
58The cancelability state and type of any newly created threads, including the
59thread in which
60.Fn main
61was first invoked, are
62.Dv PTHREAD_CANCEL_ENABLE
63and
64.Dv PTHREAD_CANCEL_DEFERRED
65respectively.
66.Pp
67The
68.Fn pthread_testcancel
69function creates a cancellation point in the calling thread.
70The
71.Fn pthread_testcancel
72function has no effect if cancelability is disabled.
984263bc
MD
73.Ss Cancelability States
74The cancelability state of a thread determines the action taken upon
75receipt of a cancellation request.
76The thread may control cancellation in
77a 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
132indicate the error.
133.Pp
134The
135.Fn pthread_setcancelstate
136and
137.Fn pthread_setcanceltype
138functions are used to control the points at which a thread may be
139asynchronously canceled.
140For cancellation control to be usable in modular
141fashion, some rules must be followed.
142.Pp
143For purposes of this discussion, consider an object to be a generalization
144of a procedure.
145It is a set of procedures and global variables written as
146a unit and called by clients not known by the object.
147Objects may depend
148on other objects.
149.Pp
150First, cancelability should only be disabled on entry to an object, never
151explicitly enabled.
152On exit from an object, the cancelability state should
153always be restored to its value on entry to the object.
154.Pp
155This follows from a modularity argument: if the client of an object (or the
156client of an object that uses that object) has disabled cancelability, it is
15acf97d 157because the client does not want to have to worry about how to clean up if the
984263bc
MD
158thread is canceled while executing some sequence of actions.
159If an object
160is called in such a state and it enables cancelability and a cancellation
161request is pending for that thread, then the thread will be canceled,
162contrary to the wish of the client that disabled.
163.Pp
164Second, the cancelability type may be explicitly set to either
165.Em deferred
166or
167.Em asynchronous
168upon entry to an object.
169But as with the cancelability state, on exit from
170an object that cancelability type should always be restored to its value on
171entry to the object.
172.Pp
173Finally, only functions that are cancel-safe may be called from a thread that
174is asynchronously cancelable.
175.Sh ERRORS
176The function
177.Fn pthread_setcancelstate
178may fail with:
179.Bl -tag -width Er
180.It Bq Er EINVAL
181The specified state is not
182.Dv PTHREAD_CANCEL_ENABLE
183or
184.Dv PTHREAD_CANCEL_DISABLE .
185.El
186.Pp
187The function
188.Fn pthread_setcanceltype
189may fail with:
190.Bl -tag -width Er
191.It Bq Er EINVAL
192The specified state is not
193.Dv PTHREAD_CANCEL_DEFERRED
194or
195.Dv PTHREAD_CANCEL_ASYNCHRONOUS .
196.El
197.Sh SEE ALSO
198.Xr pthread_cancel 3
199.Sh STANDARDS
15acf97d 200The
984263bc 201.Fn pthread_testcancel
15acf97d 202function conforms to
984263bc
MD
203.St -p1003.1-96 .
204.Sh AUTHORS
15acf97d 205This manual page was written by
984263bc
MD
206.An David Leonard Aq d@openbsd.org
207for the
208.Ox
209implementation of
210.Xr pthread_cancel 3 .