PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult 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() 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 POSIX.1‐2008, <pthread.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .