NAME

       pthread_setcancelstate,  pthread_setcanceltype,  pthread_testcancel  -  set  cancelability
       state

SYNOPSIS

       #include <pthread.h>

       int pthread_setcancelstate(int state, int *oldstate);
       int pthread_setcanceltype(int type, int *oldtype);
       void pthread_testcancel(void);

DESCRIPTION

       The pthread_setcancelstate() function shall  atomically  both  set  the  calling  thread's
       cancelability  state to the indicated state and return the previous cancelability state at
       the location referenced by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE  and
       PTHREAD_CANCEL_DISABLE.

       The  pthread_setcanceltype()  function  shall  atomically  both  set  the calling thread's
       cancelability type to the indicated type and return the previous cancelability type at the
       location  referenced  by  oldtype.  Legal  values for type are PTHREAD_CANCEL_DEFERRED and
       PTHREAD_CANCEL_ASYNCHRONOUS.

       The cancelability state and type of any newly created threads,  including  the  thread  in
       which main() was first invoked, shall be PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED
       respectively.

       The pthread_testcancel() function shall create a cancellation point in the calling thread.
       The pthread_testcancel() function shall have no effect if cancelability is disabled.

RETURN VALUE

       If  successful,  the  pthread_setcancelstate() and pthread_setcanceltype() functions shall
       return zero; otherwise, an error number shall be returned to indicate the error.

ERRORS

       The pthread_setcancelstate() function may fail if:

       EINVAL The specified state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

       The pthread_setcanceltype() function may fail if:

       EINVAL The specified type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.

       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       The pthread_setcancelstate() and pthread_setcanceltype() functions control the  points  at
       which  a  thread  may be asynchronously canceled. For cancellation control to be usable in
       modular fashion, some rules need to be followed.

       An object can be considered to be a generalization  of  a  procedure.   It  is  a  set  of
       procedures  and  global variables written as a unit and called by clients not known by the
       object. Objects may depend on other objects.

       First, cancelability should only be disabled on  entry  to  an  object,  never  explicitly
       enabled.  On exit from an object, the cancelability state should always be restored to its
       value on entry to the object.

       This follows from a modularity argument: if the client of an object (or the client  of  an
       object  that  uses  that object) has disabled cancelability, it is because the client does
       not want to be concerned about cleaning up if the thread is canceled while executing  some
       sequence  of  actions. If an object is called in such a state and it enables cancelability
       and a cancellation request is pending for  that  thread,  then  the  thread  is  canceled,
       contrary to the wish of the client that disabled.

       Second,  the  cancelability  type may be explicitly set to either deferred or asynchronous
       upon entry to an object.  But as with the cancelability state, on exit from an object  the
       cancelability type should always be restored to its value on entry to the object.

       Finally,  only  functions  that  are  cancel-safe  may  be  called  from  a thread that is
       asynchronously cancelable.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_cancel() , the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .