diff --git a/man3/pthread_setcancelstate.3 b/man3/pthread_setcancelstate.3 new file mode 100644 index 000000000..752f7005a --- /dev/null +++ b/man3/pthread_setcancelstate.3 @@ -0,0 +1,171 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.TH PTHREAD_SETCANCELSTATE 3 2008-11-14 "Linux" "Linux Programmer's Manual" +.SH NAME +pthread_setcancelstate, pthread_setcanceltype \- +set cancelability state and type +.SH SYNOPSIS +.nf +.B #include + +.BI "int pthread_setcancelstate(int " state ", int *" oldstate ); +.BI "int pthread_setcanceltype(int " type ", int *" oldtype ); +.sp +Compile and link with \fI\-pthread\fP. +.SH DESCRIPTION +The +.BR pthread_setcancelstate () +sets the cancelability state of the calling thread to the value +given in +.IR state . +The previous cancelability state of the thread is returned +in the buffer pointed to by +.IR oldstate . +The +.I state +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_ENABLE +The thread is cancelable. +This is the default cancelability state in all new threads, +including the initial thread. +The thread's cancelability type determines when a cancelable thread +will respond to a cancellation request. +.TP +.B PTHREAD_CANCEL_DISABLE +The thread is not cancelable. +If a cancellation request is received, +it is blocked until cancelability is enabled. +.PP +The +.BR pthread_setcanceltype () +sets the cancelability type of the calling thread to the value +given in +.IR type . +The previous cancelability type of the thread is returned +in the buffer pointed to by +.IR oldtype . +The +.I type +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_DEFERRED +A cancellation request is deferred until the thread next calls +a function that is a cancellation point (see +.BR pthreads (7)). +This is the default cancelability type in all new threads, +including the initial thread. +.TP +.B PTHREAD_CANCEL_ASYNCHRONOUS +The thread can be canceled at any time. +(Typically, +it will be canceled immediately upon receiving a cancellation request, +but the system doesn't guarantee this.) +.PP +The set-and-get operation performed by each of these functions +is atomic with respect to other threads in the process +calling the same function. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a non-zero error number. +.SH ERRORS +The +.BR pthread_setcancelstate () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR state . +.PP +The +.BR pthread_setcanceltype () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR type . +.\" .SH VERSIONS +.\" Available since glibc 2.0 +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES +For details of what happens when a thread is canceled, see +.BR pthread_cancel (3). + +Briefly disabling cancelability is useful +if a thread performs some critical action +that must not be interrupted by a cancellation request. +Beware of disabling cancelability for long periods, +or around operations that may block for long periods, +since that will render the thread unresponsive to cancellation requests. + +Setting the cancelability type to +.B PTHREAD_CANCEL_ASYNCHRONOUS +is rarely useful. +Since the thread could be canceled at +.I any +time, it cannot reserve resources (e.g., allocating memory), +acquire mutexes, semaphores, or locks, and so on, +since, when the thread is canceled, +the application has no way of knowing what the state of these resources is; +that is, did the canceled thread manage to release the resources or not? +(Among other things, this means that clean-up handlers cease to be useful, +since they can't determine the state of resources that +they are intended to clean up.) +In general, most library functions, including most pthreads functions, +can't be safely called from an asynchronously cancelable thread. +(POSIX.1-2001 only requires that +.BR pthread_cancel (3), +.BR pthread_setcancelstate (), +and +.BR pthread_setcanceltype () +be safe to call from an asynchronously cancelable thread.) +One of the few circumstances in which asynchronous cancelability is useful +is for cancellation of a thread that is in a pure compute-bound loop. + +The Linux threading implementations permit the +.I oldstate +argument of +.BR pthread_setcancelstate () +to be NULL, in which case the information about the previous +cancelability state is not returned to the caller. +Many other implementations also permit a NULL +.I oldstat +argument, +.\" It looks like at least Solaris, FreeBSD and Tru64 support this. +but POSIX.1-2001 does not specify this point, +so portable applications should always specify a non-NULL value in +.IR oldstate . +A precisely analogous set of statements applies for the +.I oldtype +argument of +.BR pthread_setcanceltype (). +.SH EXAMPLE +See +.BR pthread_cancel (3). +.SH SEE ALSO +.BR pthread_cleanup_push (3), +.BR pthread_cancel (3), +.BR pthread_testcancel (3), +.BR pthreads (7)