lib/libpthread/pthread_cancel.3

   1 .\" $FreeBSD: src/share/man/man3/pthread_cancel.3,v 1.13 2007/10/22 10:08:00 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 July 10, 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 The
  56 .Fn pthread_cancel
  57 function will fail if:
  58 .Bl -tag -width Er
  59 .It Bq Er ESRCH
  60 No thread could be found corresponding to that specified by the given
  61 thread ID.
  62 .El
  63 .Sh SEE ALSO
  64 .Xr pthread_cleanup_pop 3 ,
  65 .Xr pthread_cleanup_push 3 ,
  66 .Xr pthread_exit 3 ,
  67 .Xr pthread_join 3 ,
  68 .Xr pthread_setcancelstate 3 ,
  69 .Xr pthread_setcanceltype 3 ,
  70 .Xr pthread_testcancel 3
  71 .Sh STANDARDS
  72 The
  73 .Fn pthread_cancel
  74 function conforms to
  75 .St -p1003.1-96 .
  76 .Sh AUTHORS
  77 This manual page was written by
  78 .An David Leonard Aq d@openbsd.org
  79 for the
  80 .Ox
  81 implementation of
  82 .Fn pthread_cancel .