# pthread_setcancelstate

## 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



           In order to write a signal handler for an asynchronous signal
           which can run safely in a cancellable thread,
           _pthread_setcancelstate_() must be used to disable cancellation for
           the duration of any calls that the signal handler makes which are
           cancellation points. However, the standard does not permit
           strictly conforming applications to call _pthread_setcancelstate_()
           from a signal handler since it is not currently required to be
           async-signal-safe. On implementations where
           _pthread_setcancelstate_() is not async-signal-safe, alternatives
           are to ensure either that the corresponding signals are blocked
           during execution of functions that are not async-cancel-safe or
           that cancellation is disabled during times when those signals
           could be delivered. Implementations are strongly encouraged to
           make _pthread_setcancelstate_() async-signal-safe.
    


## 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



           The _pthread_setcancelstate_() function may be added to the table of
           async-signal-safe functions in _Section 2.4.3_ , _Signal Actions_.
    


* * *