Unix/Linux Go Back    


Linux 2.6 - man page for pthread_testcancel (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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  can-
       celability 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 cance-
       lability 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  proce-
       dures  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,  con-
       trary 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 asyn-
       chronously 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003			PTHREAD_SETCANCELSTATE(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:00 PM.