PTHREAD_CANCEL(3)

NAME
       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-
       tion   point.   If  oldtype  is  not  NULL,  the  previous

       cancellation state is stored in the location pointed to by
       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,  pthread_setcancelstate  and  pthread_set-
       canceltype  return  0 on success and a non-zero error code
       on error.

ERRORS
       pthread_cancel returns the following error code on error:
              ESRCH  no thread could be  found  corresponding  to
                     that specified by the thread ID.

       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 lt;Xavier.Leroy@inria.fr

SEE ALSO
       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();