PTHREAD_CANCEL(3)

NAME
pthread_cancel - cancel execution of a thread

LIBRARY
libpthread

SYNOPSIS
#include <pthread.h>
int
pthread_cancel(pthread_t thread);

DESCRIPTION
The pthread_cancel() function requests that thread be canceled. The target 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 thread 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 terminated; 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. Otherwise 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 specified by the given thread ID.

SEE ALSO
pthread_cleanup_pop(3), pthread_join(3), pthread_testcancel(3)

STANDARDS
The function conforms to p1003.1-2001.