pthread_cancel, pthread_setcancelstate, pthread_setcancel-
       type, pthread_testcancel - thread cancellation

SYNOPSIS

       #include <pthread.h>

       int pthread_cancel(pthread_t thread);

       int pthread_setcancelstate(int state, int *oldstate);

       int pthread_setcanceltype(int type, int *oldtype);

       void pthread_testcancel(void);

DESCRIPTION

       Cancellation is the mechanism by which a thread can termi-
       nate  the  execution  of another thread. More precisely, a
       thread can send a cancellation request to another  thread.
       Depending  on  its  settings,  the  target thread can then
       either ignore the request, honor it immediately, or  defer
       it till it reaches a cancellation point.

       When a thread eventually honors a cancellation request, it
       performs as  if  pthread_exit(PTHREAD_CANCELED)  has  been
       called at that point: all cleanup handlers are executed in
       reverse order, finalization functions for  thread-specific
       data  are  called,  and finally the thread stops executing
       with   the    return    value    PTHREAD_CANCELED.     See
       pthread_exit(3) for more information.

       pthread_cancel  sends a cancellation request to the thread
       denoted by the thread argument.

       pthread_setcancelstate changes the cancellation state  for
       the  calling  thread  --  that  is,  whether  cancellation
       requests are ignored or not. The state argument is the new
       cancellation state: either PTHREAD_CANCEL_ENABLE to enable
       cancellation, or PTHREAD_CANCEL_DISABLE to disable cancel-
       lation (cancellation requests are ignored). If oldstate is
       not NULL, the previous cancellation state is stored in the
       location  pointed to by oldstate, and can thus be restored
       later by another call to pthread_setcancelstate.

       pthread_setcanceltype changes the  type  of  responses  to
       cancellation requests for the calling thread: asynchronous
       (immediate) or deferred.  The type  argument  is  the  new
       cancellation  type:  either PTHREAD_CANCEL_ASYNCHRONOUS to
       cancel the calling thread  as  soon  as  the  cancellation
       request  is  received,  or PTHREAD_CANCEL_DEFERRED to keep
       the cancellation request pending until the next  cancella-
       oldtype, and can thus be restored later by another call to
       pthread_setcanceltype.

       Threads are always created by pthread_create(3) with  can-
       cellation  enabled and deferred. That is, the initial can-
       cellation state is PTHREAD_CANCEL_ENABLE and  the  initial
       type is PTHREAD_CANCEL_DEFERRED.

       Cancellation points are those points in the program execu-
       tion where a test for  pending  cancellation  requests  is
       performed  and  cancellation  is executed if positive. The
       following POSIX threads functions are cancellation points:

       pthread_join(3)
       pthread_cond_wait(3)
       pthread_cond_timedwait(3)
       pthread_testcancel(3)
       sem_wait(3)
       sigwait(3)

       All other POSIX threads functions are guaranteed not to be
       cancellation points. That is, they never perform cancella-
       tion in deferred cancellation mode.

       pthread_testcancel does nothing except testing for pending
       cancellation and executing it. Its purpose is to introduce
       explicit checks for cancellation in long sequences of code
       that do not call cancellation point functions otherwise.

RETURN VALUE

       pthread_cancel always returns  0.   pthread_setcancelstate
       and  pthread_setcanceltype  return 0 on success and a non-
       zero error code on error.

ERRORS

       pthread_setcancelstate returns the following error code on
       error:

              EINVAL the   state  argument  is  not  PTHREAD_CAN-
                     CEL_ENABLE nor PTHREAD_CANCEL_DISABLE

       pthread_setcanceltype returns the following error code  on
       error:

              EINVAL the   type   argument  is  not  PTHREAD_CAN-
                     CEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS

AUTHOR

       Xavier Leroy <Xavier.Leroy@inria.fr>
       pthread_exit(3),                  pthread_cleanup_push(3),
       pthread_cleanup_pop(3).

BUGS

       POSIX specifies that a number of system calls  (basically,
       all   system  calls  that  may  block,  such  as  read(2),
       write(2), wait(2), etc.) and library  functions  that  may
       call  these  system calls (e.g.  fprintf(3)) are cancella-
       tion points.  LinuxThreads is not  yet  integrated  enough
       with the C library to implement this, and thus none of the
       C library functions is a cancellation point.

       For system calls at least, there is a workaround.  Cancel-
       lation  requests  are  transmitted to the target thread by
       sending it a signal. That signal will interrupt all block-
       ing  system calls, causing them to return immediately with
       the EINTR error. So, checking for  cancellation  during  a
       read  system  call,  for instance, can be achieved as fol-
       lows:


              pthread_testcancel();
              retcode = read(fd, buffer, length);
              pthread_testcancel();