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 .Dd July 10, 2009
   3 .Dt PTHREAD_CANCEL 3
   4 .Os
   5 .Sh NAME
   6 .Nm pthread_cancel
   7 .Nd cancel execution of a thread
   8 .Sh LIBRARY
   9 .Lb libpthread
  10 .Sh SYNOPSIS
  11 .In pthread.h
  12 .Ft int
  13 .Fn pthread_cancel "pthread_t thread"
  14 .Sh DESCRIPTION
  15 The
  16 .Fn pthread_cancel
  17 function requests that
  18 .Fa thread
  19 be canceled.
  20 The target thread's cancelability state and type determines
  21 when the cancellation takes effect.
  22 When the cancellation is acted on,
  23 the cancellation cleanup handlers for
  24 .Fa thread
  25 are called.
  26 When the last cancellation cleanup handler returns,
  27 the thread-specific data destructor functions will be called for
  28 .Fa thread .
  29 When the last destructor function returns,
  30 .Fa thread
  31 will be terminated.
  32 .Pp
  33 The cancellation processing in the target thread runs asynchronously with
  34 respect to the calling thread returning from
  35 .Fn pthread_cancel .
  36 .Pp
  37 A status of
  38 .Dv PTHREAD_CANCELED
  39 is made available to any threads joining with the target.
  40 The symbolic
  41 constant
  42 .Dv PTHREAD_CANCELED
  43 expands to a constant expression of type
  44 .Ft "(void *)" ,
  45 whose value matches no pointer to an object in memory nor the value
  46 .Dv NULL .
  47 .Sh RETURN VALUES
  48 If successful, the
  49 .Fn pthread_cancel
  50 functions will return zero.
  51 Otherwise an error number will be returned to
  52 indicate the error.
  53 .Sh ERRORS
  54 The
  55 .Fn pthread_cancel
  56 function 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 The
  72 .Fn pthread_cancel
  73 function conforms to
  74 .St -p1003.1-96 .
  75 .Sh AUTHORS
  76 This manual page was written by
  77 .An David Leonard Aq Mt d@openbsd.org
  78 for the
  79 .Ox
  80 implementation of
  81 .Fn pthread_cancel .