Man Linux: Main Page and Category List

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 .