1.\" $NetBSD: pthread_cancel.3,v 1.6 2014/03/12 07:32:46 dholland Exp $ 2.\" 3.\" Copyright (c) 2002, 2010 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_cancel.3,v 1.7 2002/09/16 19:29:28 mini Exp $ 26.Dd July 9, 2010 27.Dt PTHREAD_CANCEL 3 28.Os 29.Sh NAME 30.Nm pthread_cancel 31.Nd cancel execution of a thread 32.Sh LIBRARY 33.Lb libpthread 34.Sh SYNOPSIS 35.In pthread.h 36.Ft int 37.Fn pthread_cancel "pthread_t thread" 38.Sh DESCRIPTION 39The 40.Fn pthread_cancel 41function requests that 42.Fa thread 43be canceled. 44The target thread's cancelability state and type determines 45whether and when the target thread reacts to the cancellation request. 46.Bl -enum -offset 2n 47.It 48The cancelability 49.Em state 50of a thread is determined by the 51.Xr pthread_setcancelstate 3 52function. 53The state can be either: 54.Bl -bullet -offset 2n 55.It 56.Dv PTHREAD_CANCEL_ENABLE : 57the cancelability type determines when the actual cancellation occurs. 58This is the default. 59.It 60.Dv PTHREAD_CANCEL_DISABLE : 61the request from 62.Fn pthread_cancel 63remains queued until the cancellation is enabled by the thread. 64.El 65.It 66The cancellation 67.Em type 68of a thread is determined by the 69.Xr pthread_setcanceltype 3 70function. 71The type can be either: 72.Bl -bullet -offset 2n 73.It 74.Dv PTHREAD_CANCEL_DEFERRED : 75the cancellation will be delayed until the thread calls 76a function that is a cancellation point. 77This is the default. 78The available cancellation points are listed in 79.Xr pthread_setcanceltype 3 . 80.It 81.Dv PTHREAD_CANCEL_ASYNCHRONOUS : 82the thread can be canceled at any time. 83.El 84.El 85.Pp 86When the thread reacts to the cancellation request, the following occur: 87.Bl -enum -offset 2n 88.It 89The cancellation cleanup handlers for the thread are called; see 90.Xr pthread_cleanup_push 3 . 91.It 92When the last cancellation cleanup handler returns, 93the thread-specific data destructor functions will be called for the thread. 94.It 95When the last destructor function returns, the thread will be terminated; see 96.Xr pthread_exit 3 . 97.El 98.Pp 99The cancellation processing in the target thread runs asynchronously with 100respect to the calling thread returning from 101.Fn pthread_cancel . 102.Pp 103A status of 104.Dv PTHREAD_CANCELED 105is made available to any threads joining with the target. 106The symbolic 107constant 108.Dv PTHREAD_CANCELED 109expands to a constant expression of type 110.Ft (void *) , 111whose value matches no pointer to an object in memory nor the value 112.Dv NULL . 113.Sh RETURN VALUES 114If successful, the 115.Fn pthread_cancel 116functions will return zero. 117Otherwise an error number will be returned to 118indicate the error. 119.Sh ERRORS 120The 121.Fn pthread_cancel 122function may fail if: 123.Bl -tag -width Er 124.It Bq Er ESRCH 125No thread could be found corresponding to that specified by the given 126thread ID. 127.El 128.Sh SEE ALSO 129.Xr pthread_cleanup_pop 3 , 130.Xr pthread_join 3 , 131.Xr pthread_testcancel 3 132.Sh STANDARDS 133The function conforms to 134.St -p1003.1-2001 . 135