pthread_cancel(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PTHREAD_CANCEL(3)       NetBSD Library Functions Manual      PTHREAD_CANCEL(3)


NAME

     pthread_cancel -- cancel execution of a thread


LIBRARY

     POSIX Threads Library (libpthread, -lpthread)


SYNOPSIS

     #include <pthread.h>

     int
     pthread_cancel(pthread_t thread);


DESCRIPTION

     The pthread_cancel() function requests that thread be canceled.  The tar-
     get thread's cancelability state and type determines whether and when the
     target thread reacts to the cancellation request.

       1.   The cancelability state of a thread is determined by the
            pthread_setcancelstate(3) function.  The state can be either:

              ·   PTHREAD_CANCEL_ENABLE: the cancelability type determines
                  when the actual cancellation occurs.  This is the default.

              ·   PTHREAD_CANCEL_DISABLE: the request from pthread_cancel()
                  remains queued until the cancellation is enabled by the
                  thread.

       2.   The cancellation type of a thread is determined by the
            pthread_setcanceltype(3) function.  The type can be either:

              ·   PTHREAD_CANCEL_DEFERRED: the cancellation will be delayed
                  until the thread calls a function that is a cancellation
                  point.  This is the default.  The available cancellation
                  points are listed in pthread_setcanceltype(3).

              ·   PTHREAD_CANCEL_ASYNCHRONOUS: the thread can be canceled at
                  any time.

     When the tread reacts to the cancellation request, the following occur:

       1.   The cancellation cleanup handlers for the thread are called; see
            pthread_cleanup_push(3).

       2.   When the last cancellation cleanup handler returns, the thread-
            specific data destructor functions will be called for the thread.

       3.   When the last destructor function returns, the thread will be ter-
            minated; see pthread_exit(3).

     The cancellation processing in the target thread runs asynchronously with
     respect to the calling thread returning from pthread_cancel().

     A status of PTHREAD_CANCELED is made available to any threads joining
     with the target.  The symbolic constant PTHREAD_CANCELED expands to a
     constant expression of type (void *), whose value matches no pointer to
     an object in memory nor the value NULL.


RETURN VALUES

     If successful,  the pthread_cancel() functions will return zero.  Other-
     wise an error number will be returned to indicate the error.


ERRORS

     The pthread_cancel() function may fail if:

     [ESRCH]            No thread could be found corresponding to that speci-
                        fied by the given thread ID.


SEE ALSO

     pthread_cleanup_pop(3), pthread_join(3), pthread_testcancel(3)


STANDARDS

     The function conforms to IEEE Std 1003.1-2001 (``POSIX.1'').

NetBSD 6.0                       July 9, 2010                       NetBSD 6.0