PTHREAD_SETCANCELSTATE(3P)                          POSIX Programmer's Manual                         PTHREAD_SETCANCELSTATE(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

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() func-
       tion 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  asyn-
       chronously 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 writ-
       ten 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,  Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                    PTHREAD_SETCANCELSTATE(3P)