--------------------------------------------------------------------------------
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume
                                       1
--------------------------------------------------------------------------------

pthread_cancel Subroutine

Purpose

Requests the cancellation of a thread.

Library

Threads Library (libpthreads.a)

Syntax

#include 

int pthread_cancel (pthread_t thread);

Description

The pthread_cancel subroutine requests the cancellation of the thread thread. The
action depends on the cancelability of the target thread:

  o If its cancelability is disabled, the cancellation request is set pending.
  o If its cancelability is deferred, the cancellation request is set pending
    till the thread reaches a cancellation point.
  o If its cancelability is asynchronous, the cancellation request is acted upon
    immediately; in some cases, it may result in unexpected behaviour.

The cancellation of a thread terminates it safely, using the same termination
procedure as the pthread_exit subroutine.

    Note: The pthread.h header file must be the first included file of each
    source file using the threads library. Otherwise, the -D_THREAD_SAFE
    compilation flag should be used, or the cc_r compiler used. In this case, the
    flag is automatically set.

Parameters

thread Specifies the thread to be canceled.

Return Values

If successful, the pthread_cancel function returns zero. Otherwise, an error
number is returned to indicate the error.

Error Codes

The ptread_cancel function may fail if:

ESRCH No thread could be found corresponding to that specified by the given
thread ID.

The pthread_cancel function will not return an error code of EINTR.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The pthread_kill subroutine, pthread_exit subroutine, pthread_join subroutine,
pthread_cond_wait, and pthread_cond_timedwait subroutines.

The pthread.h file.

Terminating Threads in AIX Version 4.3 General Programming Concepts: Writing and
Debugging Programs.

Threads Library Quick Reference in AIX Version 4.3 General Programming Concepts:
Writing and Debugging Programs.
--------------------------------------------------------------------------------