Ubuntu Manpage: This manual page is part of the POSIX Programmer's Manual. The Linux implementation of

Provided by: manpages-posix-dev_2017a-2_all

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.

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1-2017,  Standard  for  Information Technology -- Portable Operating System Interface
       (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C)  2018  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 .

       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 .