PTHREAD_CANCEL(3)

PTHREAD_CANCEL(3) | 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 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 IEEE Std 1003.1-2001 (“POSIX.1”).

July 9, 2010 | NetBSD 9.3