Merge branch 'master' of ssh://crater.dragonflybsd.org/repository/git/dragonfly
[dragonfly.git] / lib / libpthread / pthread_cancel.3
blob93aecba8a2d3e9a402f94d58028b71aa8f3cd989
1 .\" $FreeBSD: src/lib/libc_r/man/pthread_cancel.3,v 1.3.2.4 2001/12/17 10:08:26 ru Exp $
2 .\" $DragonFly: src/lib/libc_r/man/pthread_cancel.3,v 1.2 2003/06/17 04:26:47 dillon Exp $
3 .Dd April 15, 2009
4 .Dt PTHREAD_CANCEL 3
5 .Os
6 .Sh NAME
7 .Nm pthread_cancel
8 .Nd cancel execution of a thread
9 .Sh LIBRARY
10 .Lb libpthread
11 .Sh SYNOPSIS
12 .In pthread.h
13 .Ft int
14 .Fn pthread_cancel "pthread_t thread"
15 .Sh DESCRIPTION
16 The
17 .Fn pthread_cancel
18 function requests that
19 .Fa thread
20 be canceled.
21 The target thread's cancelability state and type determines
22 when the cancellation takes effect.
23 When the cancellation is acted on,
24 the cancellation cleanup handlers for
25 .Fa thread
26 are called.
27 When the last cancellation cleanup handler returns,
28 the thread-specific data destructor functions will be called for
29 .Fa thread .
30 When the last destructor function returns,
31 .Fa thread
32 will be terminated.
33 .Pp
34 The cancellation processing in the target thread runs asynchronously with
35 respect to the calling thread returning from
36 .Fn pthread_cancel .
37 .Pp
38 A status of
39 .Dv PTHREAD_CANCELED
40 is made available to any threads joining with the target.
41 The symbolic
42 constant
43 .Dv PTHREAD_CANCELED
44 expands to a constant expression of type
45 .Ft "(void *)" ,
46 whose value matches no pointer to an object in memory nor the value
47 .Dv NULL .
48 .Sh RETURN VALUES
49 If successful,  the
50 .Fn pthread_cancel
51 functions will return zero.
52 Otherwise an error number will be returned to
53 indicate the error.
54 .Sh ERRORS
55 .Fn pthread_cancel
56 will fail if:
57 .Bl -tag -width Er
58 .It Bq Er ESRCH
59 No thread could be found corresponding to that specified by the given
60 thread ID.
61 .El
62 .Sh SEE ALSO
63 .Xr pthread_cleanup_pop 3 ,
64 .Xr pthread_cleanup_push 3 ,
65 .Xr pthread_exit 3 ,
66 .Xr pthread_join 3 ,
67 .Xr pthread_setcancelstate 3 ,
68 .Xr pthread_setcanceltype 3 ,
69 .Xr pthread_testcancel 3
70 .Sh STANDARDS
71 .Fn pthread_cancel
72 conforms to
73 .St -p1003.1-96 .
74 .Sh AUTHORS
75 This man page was written by
76 .An David Leonard Aq d@openbsd.org
77 for the
78 .Ox
79 implementation of
80 .Fn pthread_cancel .