#include <pthread.h>
int pthread_cancel(pthread_t thread);
Threadsafe: Yes
Signal Safe: No

The pthread_cancel() function requests cancelation of the target thread. The target thread is canceled, based on its cancelability state.

Cancelability consists of 3 separate states (disabled, deferred, asynchronous) that can be represented by 2 boolean values.

Cancelability	Cancelability State	Cancelability Type
disabled	PTHREAD_CANCEL_DISABLE	PTHREAD_CANCEL_DEFERRED
disabled	PTHREAD_CANCEL_DISABLE	PTHREAD_CANCEL_ASYNCHRONOUS
deferred	PTHREAD_CANCEL_ENABLE	PTHREAD_CANCEL_DEFERRED
asynchronous	PTHREAD_CANCEL_ENABLE	PTHREAD_CANCEL_ASYNCHRONOUS

The default cancelability state is deferred.

When cancelability is disabled, all cancels are held pending in the target thread until the thread changes the cancelability. When cancelability is deferred, all cancels are held pending in the target thread until the thread changes the cancelability, calls a function which is a cancelation point or calls pthread_testcancel(), thus creating a cancelation point. When cancelability is asynchronous, all cancels are acted upon immediately, interrupting the thread with its processing.

It is recommended that your application not use asynchronous thread cancelation via the PTHREAD_CANCEL_ASYNCHRONOUS option of pthread_setcanceltype(). See the common user errors section of this document for more information.

The following functions are cancelation points:

• pthread_cond_timedwait()
• pthread_cond_wait()
• pthread_join()
• pthread_join_np()
• pthread_extendedjoin_np()
• pthread_testcancel()

1. The thread invokes cancelation cleanup handlers with cancelation disabled until the last cancelation cleanup handler returns. The handlers are invoked in LIFO (Last In, First Out) order.
2. Data destructors are called for any thread specific data entries that have a non NULL value for both the value and the destructor.
3. When the last cancelation cleanup handler returns, the thread is terminated and a status of PTHREAD_CANCELED is made available to any threads joining with the target.
4. Any mutexes that are held by a thread that terminates, become `abandoned' and are no longer valid. Subsequent calls by other threads that attempt to acquire the abandoned mutex (though pthread_mutex_lock() or pthread_mutex_trylock()) will fail with an EOWNERTERM error.
5. No release of any application visible process resources occur. This includes but is not limited to mutexes, file descriptors, or any process level cleanup actions.

Note that in the OS/400 implementation of threads, the initial thread is special. Termination of the initial thread via pthread_exit(), pthread_cancel() or any other thread termination mechanism terminates the entire process.

Parameters

thread

(Input) Pthread handle to the target thread

None.

Return Value

0

pthread_cancel() was successful.

value

pthread_cancel() was not successful. value is set to indicate the error condition.

If pthread_cancel() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[ESRCH]

No thread could be found that matched the thread id specified.

• The <pthread.h> header file. See Header files for Pthread functions
• pthread_cleanup_pop()--Pop a Cleanup Handler off of the Cancelation Cleanup Stack
• pthread_cleanup_push()--Push a Cleanup Handler onto the Cancelation Cleanup Stack
• pthread_exit()--Terminate The Calling Thread
• pthread_setcancelstate()--Set Cancel State
• pthread_setcanceltype()--Set Cancel Type

#include <pthread.h>
#include <stdio.h>
#include "check.h"

void *threadfunc(void *parm)
{
  printf("Entered secondary thread\n");
  while (1) {
    printf("Secondary thread is looping\n");
    pthread_testcancel();
    sleep(1);
  }
  return NULL;
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;

  printf("Entering testcase\n");
  
  /* Create a thread using default attributes */
  printf("Create thread using the NULL attributes\n");
  rc = pthread_create(&thread, NULL, threadfunc, NULL);
  checkResults("pthread_create(NULL)\n", rc);
  
  /* sleep() isn't a very robust way to wait for the thread */
  sleep(2);

  printf("Cancel the thread\n");
  rc = pthread_cancel(thread);
  checkResults("pthread_cancel()\n", rc);

  /* sleep() isn't a very robust way to wait for the thread */
  sleep(3);
  printf("Main completed\n");
  return 0;
}

Entering testcase
Create thread using the NULL attributes
Entered secondary thread
Secondary thread is looping
Secondary thread is looping
Cancel the thread
Main completed