1.\" $NetBSD: pthread_testcancel.3,v 1.9 2014/03/18 18:20:38 riastradh Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 14.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 17.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 23.\" POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/lib/libpthread/man/pthread_testcancel.3,v 1.9 2002/09/16 19:29:29 mini Exp $ 26.Dd August 6, 2010 27.Dt PTHREAD_TESTCANCEL 3 28.Os 29.Sh NAME 30.Nm pthread_setcancelstate , 31.Nm pthread_setcanceltype , 32.Nm pthread_testcancel 33.Nd set cancelability state 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread.h 38.Ft int 39.Fn pthread_setcancelstate "int state" "int *oldstate" 40.Ft int 41.Fn pthread_setcanceltype "int type" "int *oldtype" 42.Ft void 43.Fn pthread_testcancel "void" 44.Sh DESCRIPTION 45The 46.Fn pthread_setcancelstate 47function atomically both sets the calling thread's cancelability state 48to the indicated 49.Fa state 50and, if 51.Fa oldstate 52is not 53.Dv NULL , 54returns the previous cancelability state at the location referenced by 55.Fa oldstate . 56Legal values for 57.Fa state 58are 59.Dv PTHREAD_CANCEL_ENABLE 60and 61.Dv PTHREAD_CANCEL_DISABLE . 62.Pp 63The 64.Fn pthread_setcanceltype 65function atomically both sets the calling thread's cancelability type 66to the indicated 67.Fa type 68and, if 69.Fa oldtype 70is not 71.Dv NULL , 72returns the previous cancelability type at the location referenced by 73.Fa oldtype . 74Legal values for 75.Fa type 76are 77.Dv PTHREAD_CANCEL_DEFERRED 78and 79.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 80.Pp 81The cancelability state and type of any newly created threads, including the 82thread in which 83.Fn main 84was first invoked, are 85.Dv PTHREAD_CANCEL_ENABLE 86and 87.Dv PTHREAD_CANCEL_DEFERRED 88respectively. 89.Pp 90The 91.Fn pthread_testcancel 92function creates a cancellation point in the calling thread. 93The 94.Fn pthread_testcancel 95function has no effect if cancelability is disabled. 96.Ss Cancelability States 97The cancelability state of a thread determines the action taken upon 98receipt of a cancellation request. 99The thread may control cancellation in 100a number of ways. 101.Pp 102Each thread maintains its own 103.Dq cancelability state 104which may be encoded in two bits: 105.Bl -hang 106.It Em Cancelability Enable 107When cancelability is 108.Dv PTHREAD_CANCEL_DISABLE , 109cancellation requests against the target thread are held pending. 110.It Em Cancelability Type 111When cancelability is enabled and the cancelability type is 112.Dv PTHREAD_CANCEL_ASYNCHRONOUS , 113new or pending cancellation requests may be acted upon at any time. 114When cancelability is enabled and the cancelability type is 115.Dv PTHREAD_CANCEL_DEFERRED , 116cancellation requests are held pending until a cancellation point (see 117below) is reached. 118If cancelability is disabled, the setting of the 119cancelability type has no immediate effect as all cancellation requests 120are held pending; however, once cancelability is enabled again the new 121type will be in effect. 122.El 123.Ss Cancellation Points 124Cancellation points will occur when a thread is executing the following 125functions: 126.Fn accept , 127.Fn aio_suspend , 128.Fn clock_nanosleep , 129.Fn close , 130.Fn connect , 131.Fn creat , 132.Fn fcntl , 133.Fn fdatasync , 134.Fn fsync , 135.Fn fsync_range , 136.\".Fn getmsg , 137.\".Fn getpmsg , 138.Fn kevent , 139.\".Fn lockf , 140.Fn mq_receive , 141.Fn mq_send , 142.Fn mq_timedreceive , 143.Fn mq_timedsend , 144.Fn msgrcv , 145.Fn msgsnd , 146.Fn msync , 147.Fn nanosleep , 148.Fn open , 149.Fn pause , 150.Fn poll , 151.Fn pollts , 152.Fn pread , 153.Fn pselect , 154.Fn pthread_cond_timedwait , 155.Fn pthread_cond_wait , 156.Fn pthread_join , 157.Fn pthread_testcancel , 158.\".Fn putmsg , 159.\".Fn putpmsg , 160.Fn pwrite , 161.Fn read , 162.Fn readv , 163.Fn recv , 164.Fn recvfrom , 165.Fn recvmsg , 166.Fn select , 167.Fn sem_timedwait , 168.Fn sem_wait , 169.Fn send , 170.Fn sendmsg , 171.Fn sendto , 172.Fn sigpause , 173.Fn sigsuspend , 174.Fn sigtimedwait , 175.Fn sigwait , 176.Fn sigwaitinfo , 177.Fn sleep , 178.Fn system , 179.Fn tcdrain , 180.Fn usleep , 181.Fn wait , 182.Fn wait4 , 183.Fn waitid , 184.Fn waitpid , 185.Fn write , 186and 187.Fn writev . 188.Sh RETURN VALUES 189If successful, the 190.Fn pthread_setcancelstate 191and 192.Fn pthread_setcanceltype 193functions will return zero. 194Otherwise, an error number shall be returned to 195indicate the error. 196.Pp 197The 198.Fn pthread_setcancelstate 199and 200.Fn pthread_setcanceltype 201functions are used to control the points at which a thread may be 202asynchronously canceled. 203For cancellation control to be usable in modular 204fashion, some rules must be followed. 205.Pp 206For purposes of this discussion, consider an object to be a generalization 207of a procedure. 208It is a set of procedures and global variables written as 209a unit and called by clients not known by the object. 210Objects may depend 211on other objects. 212.Pp 213First, cancelability should only be disabled on entry to an object, never 214explicitly enabled. 215On exit from an object, the cancelability state should 216always be restored to its value on entry to the object. 217.Pp 218This follows from a modularity argument: if the client of an object (or the 219client of an object that uses that object) has disabled cancelability, it is 220because the client doesn't want to have to worry about how to clean up if the 221thread is canceled while executing some sequence of actions. 222If an object 223is called in such a state and it enables cancelability and a cancellation 224request is pending for that thread, then the thread will be canceled, 225contrary to the wish of the client that disabled. 226.Pp 227Second, the cancelability type may be explicitly set to either 228.Em deferred 229or 230.Em asynchronous 231upon entry to an object. 232But as with the cancelability state, on exit from 233an object that cancelability type should always be restored to its value on 234entry to the object. 235.Pp 236Finally, only functions that are cancel-safe may be called from a thread that 237is asynchronously cancelable. 238.Sh ERRORS 239The function 240.Fn pthread_setcancelstate 241may fail with: 242.Bl -tag -width Er 243.It Bq Er EINVAL 244The specified state is not 245.Dv PTHREAD_CANCEL_ENABLE 246or 247.Dv PTHREAD_CANCEL_DISABLE . 248.El 249.Pp 250The function 251.Fn pthread_setcanceltype 252may fail with: 253.Bl -tag -width Er 254.It Bq Er EINVAL 255The specified state is not 256.Dv PTHREAD_CANCEL_DEFERRED 257or 258.Dv PTHREAD_CANCEL_ASYNCHRONOUS . 259.El 260.Sh SEE ALSO 261.Xr pthread_cancel 3 262.Sh STANDARDS 263These functions conform to 264.St -p1003.1-2001 . 265.Sh AUTHORS 266This man page was written by 267.An David Leonard Aq Mt d@openbsd.org 268for the 269.Ox 270implementation of 271.Xr pthread_cancel 3 . 272