Provided by: glibc-doc_2.9-0ubuntu6_all
 

NAME

        pthread_cancel,      pthread_setcancelstate,     pthread_setcanceltype,
        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 terminate the  exe-
        cution of another thread. More precisely, a thread can send a cancella-
        tion 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 exe-
        cuting 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_CAN-
        CEL_ENABLE to enable cancellation, or PTHREAD_CANCEL_DISABLE to disable
        cancellation (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_CAN-
        CEL_ASYNCHRONOUS to cancel the calling thread as soon as the  cancella-
        tion  request  is received, or PTHREAD_CANCEL_DEFERRED to keep the can-
        cellation request pending until the next cancellation 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 cancellation
        enabled and deferred.  That  is,  the  initial  cancellation  state  is
        PTHREAD_CANCEL_ENABLE  and the initial type is PTHREAD_CANCEL_DEFERRED.
 
        Cancellation points are those points in the program execution  where  a
        test for pending cancellation requests is performed and cancellation is
        executed if positive. The following POSIX threads functions are cancel-
        lation 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 cancellation in deferred  cancella-
        tion mode.
 
        pthread_testcancel does nothing except testing for pending cancellation
        and executing it. Its purpose is to introduce explicit checks for  can-
        cellation in long sequences of code that do not call cancellation point
        functions otherwise.
        pthread_cancel, pthread_setcancelstate and pthread_setcanceltype 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_CANCEL_ENABLE  nor
                      PTHREAD_CANCEL_DISABLE
 
        pthread_setcanceltype returns the following error code on error:
 
               EINVAL the  type  argument  is  not  PTHREAD_CANCEL_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  cancellation  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. Cancellation requests
        are transmitted to the target thread by sending it a signal. That  sig-
        nal  will  interrupt  all blocking 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 follows:
 
               pthread_testcancel();
               retcode = read(fd, buffer, length);
               pthread_testcancel();
 
                                  LinuxThreads                PTHREAD_CANCEL(3)