diff options
Diffstat (limited to 'static/freebsd/man3/pthread_testcancel.3 3.html')
| -rw-r--r-- | static/freebsd/man3/pthread_testcancel.3 3.html | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/static/freebsd/man3/pthread_testcancel.3 3.html b/static/freebsd/man3/pthread_testcancel.3 3.html new file mode 100644 index 00000000..27a2a47d --- /dev/null +++ b/static/freebsd/man3/pthread_testcancel.3 3.html @@ -0,0 +1,302 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PTHREAD_TESTCANCEL(3)</td> + <td class="head-vol">Library Functions Manual</td> + <td class="head-rtitle">PTHREAD_TESTCANCEL(3)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">pthread_setcancelstate</code>, + <code class="Nm">pthread_setcanceltype</code>, + <code class="Nm">pthread_testcancel</code> — <span class="Nd">set + cancelability state</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1> +<p class="Pp"><span class="Lb">POSIX Threads Library (libpthread, + -lpthread)</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">pthread.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pthread_setcancelstate</code>(<var class="Fa" style="white-space: nowrap;">int + state</var>, <var class="Fa" style="white-space: nowrap;">int + *oldstate</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pthread_setcanceltype</code>(<var class="Fa" style="white-space: nowrap;">int + type</var>, <var class="Fa" style="white-space: nowrap;">int + *oldtype</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pthread_testcancel</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#pthread_setcancelstate"><code class="Fn" id="pthread_setcancelstate">pthread_setcancelstate</code></a>() + function atomically both sets the calling thread's cancelability state to + the indicated <var class="Fa">state</var> and, if + <var class="Fa">oldstate</var> is not <code class="Dv">NULL</code>, returns + the previous cancelability state at the location referenced by + <var class="Fa">oldstate</var>. Legal values for <var class="Fa">state</var> + are <code class="Dv">PTHREAD_CANCEL_ENABLE</code> and + <code class="Dv">PTHREAD_CANCEL_DISABLE</code>. The function is + async-signal-safe.</p> +<p class="Pp" id="pthread_setcanceltype">The + <a class="permalink" href="#pthread_setcanceltype"><code class="Fn">pthread_setcanceltype</code></a>() + function atomically both sets the calling thread's cancelability type to the + indicated <var class="Fa">type</var> and, if <var class="Fa">oldtype</var> + is not <code class="Dv">NULL</code>, returns the previous cancelability type + at the location referenced by <var class="Fa">oldtype</var>. Legal values + for <var class="Fa">type</var> are + <code class="Dv">PTHREAD_CANCEL_DEFERRED</code> and + <code class="Dv">PTHREAD_CANCEL_ASYNCHRONOUS</code>.</p> +<p class="Pp" id="main">The cancelability state and type of any newly created + threads, including the thread in which + <a class="permalink" href="#main"><code class="Fn">main</code></a>() was + first invoked, are <code class="Dv">PTHREAD_CANCEL_ENABLE</code> and + <code class="Dv">PTHREAD_CANCEL_DEFERRED</code> respectively.</p> +<p class="Pp" id="pthread_testcancel">The + <a class="permalink" href="#pthread_testcancel"><code class="Fn">pthread_testcancel</code></a>() + function creates a cancellation point in the calling thread. The + <code class="Fn">pthread_testcancel</code>() function has no effect if + cancelability is disabled.</p> +<section class="Ss"> +<h2 class="Ss" id="Cancelability_States"><a class="permalink" href="#Cancelability_States">Cancelability + States</a></h2> +<p class="Pp">The cancelability state of a thread determines the action taken + upon receipt of a cancellation request. The thread may control cancellation + in a number of ways.</p> +<p class="Pp">Each thread maintains its own “cancelability state” + which may be encoded in two bits:</p> +<dl class="Bl-hang"> + <dt id="Cancelability"><a class="permalink" href="#Cancelability"><i class="Em">Cancelability + Enable</i></a></dt> + <dd>When cancelability is <code class="Dv">PTHREAD_CANCEL_DISABLE</code>, + cancellation requests against the target thread are held pending.</dd> + <dt id="Cancelability~2"><a class="permalink" href="#Cancelability~2"><i class="Em">Cancelability + Type</i></a></dt> + <dd>When cancelability is enabled and the cancelability type is + <code class="Dv">PTHREAD_CANCEL_ASYNCHRONOUS</code>, new or pending + cancellation requests may be acted upon at any time. When cancelability is + enabled and the cancelability type is + <code class="Dv">PTHREAD_CANCEL_DEFERRED</code>, cancellation requests are + held pending until a cancellation point (see below) is reached. If + cancelability is disabled, the setting of the cancelability type has no + immediate effect as all cancellation requests are held pending; however, + once cancelability is enabled again the new type will be in effect.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Cancellation_Points"><a class="permalink" href="#Cancellation_Points">Cancellation + Points</a></h2> +<p class="Pp">Cancellation points will occur when a thread is executing the + following functions:</p> +<dl class="Bl-tag Bl-compact"> + <dt id="accept"><a class="permalink" href="#accept"><code class="Fn">accept</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="accept4"><a class="permalink" href="#accept4"><code class="Fn">accept4</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="aio_suspend"><a class="permalink" href="#aio_suspend"><code class="Fn">aio_suspend</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="connect"><a class="permalink" href="#connect"><code class="Fn">connect</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="clock_nanosleep"><a class="permalink" href="#clock_nanosleep"><code class="Fn">clock_nanosleep</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="close"><a class="permalink" href="#close"><code class="Fn">close</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="creat"><a class="permalink" href="#creat"><code class="Fn">creat</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="fcntl"><a class="permalink" href="#fcntl"><code class="Fn">fcntl</code></a>()</dt> + <dd>The <code class="Fn">fcntl</code>() function is a cancellation point if + <var class="Fa">cmd</var> is <code class="Dv">F_SETLKW</code>.</dd> + <dt id="fdatasync"><a class="permalink" href="#fdatasync"><code class="Fn">fdatasync</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="fsync"><a class="permalink" href="#fsync"><code class="Fn">fsync</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="kevent"><a class="permalink" href="#kevent"><code class="Fn">kevent</code></a>()</dt> + <dd>The <code class="Fn">kevent</code>() function is a cancellation point if + it is potentially blocking, such as when the <var class="Fa">nevents</var> + argument is non-zero.</dd> + <dt id="mq_receive"><a class="permalink" href="#mq_receive"><code class="Fn">mq_receive</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="mq_send"><a class="permalink" href="#mq_send"><code class="Fn">mq_send</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="mq_timedreceive"><a class="permalink" href="#mq_timedreceive"><code class="Fn">mq_timedreceive</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="mq_timedsend"><a class="permalink" href="#mq_timedsend"><code class="Fn">mq_timedsend</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="msync"><a class="permalink" href="#msync"><code class="Fn">msync</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="nanosleep"><a class="permalink" href="#nanosleep"><code class="Fn">nanosleep</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="open"><a class="permalink" href="#open"><code class="Fn">open</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="openat"><a class="permalink" href="#openat"><code class="Fn">openat</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="pause"><a class="permalink" href="#pause"><code class="Fn">pause</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="poll"><a class="permalink" href="#poll"><code class="Fn">poll</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="ppoll"><a class="permalink" href="#ppoll"><code class="Fn">ppoll</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="pselect"><a class="permalink" href="#pselect"><code class="Fn">pselect</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="pthread_cond_timedwait"><a class="permalink" href="#pthread_cond_timedwait"><code class="Fn">pthread_cond_timedwait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="pthread_cond_wait"><a class="permalink" href="#pthread_cond_wait"><code class="Fn">pthread_cond_wait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="pthread_join"><a class="permalink" href="#pthread_join"><code class="Fn">pthread_join</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt><code class="Fn">pthread_testcancel</code>()</dt> + <dd style="width: auto;"> </dd> + <dt id="read"><a class="permalink" href="#read"><code class="Fn">read</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="readv"><a class="permalink" href="#readv"><code class="Fn">readv</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="recv"><a class="permalink" href="#recv"><code class="Fn">recv</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="recvfrom"><a class="permalink" href="#recvfrom"><code class="Fn">recvfrom</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="recvmsg"><a class="permalink" href="#recvmsg"><code class="Fn">recvmsg</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="select"><a class="permalink" href="#select"><code class="Fn">select</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sem_timedwait"><a class="permalink" href="#sem_timedwait"><code class="Fn">sem_timedwait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sem_clockwait_np"><a class="permalink" href="#sem_clockwait_np"><code class="Fn">sem_clockwait_np</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sem_wait"><a class="permalink" href="#sem_wait"><code class="Fn">sem_wait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="send"><a class="permalink" href="#send"><code class="Fn">send</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sendmsg"><a class="permalink" href="#sendmsg"><code class="Fn">sendmsg</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sendto"><a class="permalink" href="#sendto"><code class="Fn">sendto</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sigsuspend"><a class="permalink" href="#sigsuspend"><code class="Fn">sigsuspend</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sigtimedwait"><a class="permalink" href="#sigtimedwait"><code class="Fn">sigtimedwait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sigwaitinfo"><a class="permalink" href="#sigwaitinfo"><code class="Fn">sigwaitinfo</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sigwait"><a class="permalink" href="#sigwait"><code class="Fn">sigwait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="sleep"><a class="permalink" href="#sleep"><code class="Fn">sleep</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="system"><a class="permalink" href="#system"><code class="Fn">system</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="tcdrain"><a class="permalink" href="#tcdrain"><code class="Fn">tcdrain</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="usleep"><a class="permalink" href="#usleep"><code class="Fn">usleep</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="wait"><a class="permalink" href="#wait"><code class="Fn">wait</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="wait3"><a class="permalink" href="#wait3"><code class="Fn">wait3</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="wait4"><a class="permalink" href="#wait4"><code class="Fn">wait4</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="wait6"><a class="permalink" href="#wait6"><code class="Fn">wait6</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="waitid"><a class="permalink" href="#waitid"><code class="Fn">waitid</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="waitpid"><a class="permalink" href="#waitpid"><code class="Fn">waitpid</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="write"><a class="permalink" href="#write"><code class="Fn">write</code></a>()</dt> + <dd style="width: auto;"> </dd> + <dt id="writev"><a class="permalink" href="#writev"><code class="Fn">writev</code></a>()</dt> + <dd style="width: auto;"> </dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">The <code class="Fn">pthread_setcancelstate</code>() and + <code class="Fn">pthread_setcanceltype</code>() functions are used to + control the points at which a thread may be asynchronously canceled. For + cancellation control to be usable in modular fashion, some rules must be + followed.</p> +<p class="Pp">For purposes of this discussion, consider an object 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.</p> +<p class="Pp">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.</p> +<p class="Pp">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 have to worry about + how to clean 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 will + be canceled, contrary to the wish of the client that disabled.</p> +<p class="Pp" id="deferred">Second, the cancelability type may be explicitly set + to either + <a class="permalink" href="#deferred"><i class="Em">deferred</i></a> or + <a class="permalink" href="#asynchronous"><i class="Em" id="asynchronous">asynchronous</i></a> + upon entry to an object. But as with the cancelability state, on exit from + an object that cancelability type should always be restored to its value on + entry to the object.</p> +<p class="Pp">Finally, only functions that are cancel-safe may be called from a + thread that is asynchronously cancelable.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">If successful, the + <code class="Fn">pthread_setcancelstate</code>() and + <code class="Fn">pthread_setcanceltype</code>() functions will return zero. + Otherwise, an error number shall be returned to indicate the error.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> +<p class="Pp">The function <code class="Fn">pthread_setcancelstate</code>() may + fail with:</p> +<dl class="Bl-tag"> + <dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt> + <dd>The specified state is not <code class="Dv">PTHREAD_CANCEL_ENABLE</code> + or <code class="Dv">PTHREAD_CANCEL_DISABLE</code>.</dd> +</dl> +<p class="Pp">The function <code class="Fn">pthread_setcanceltype</code>() may + fail with:</p> +<dl class="Bl-tag"> + <dt id="EINVAL~2">[<a class="permalink" href="#EINVAL~2"><code class="Er">EINVAL</code></a>]</dt> + <dd>The specified state is not <code class="Dv">PTHREAD_CANCEL_DEFERRED</code> + or <code class="Dv">PTHREAD_CANCEL_ASYNCHRONOUS</code>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">pthread_cancel(3)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1> +<p class="Pp">The <code class="Fn">pthread_testcancel</code>() function conforms + to <span class="St">ISO/IEC 9945-1:1996 (“POSIX.1”)</span>. + The standard allows implementations to make many more functions cancellation + points.</p> +<p class="Pp">The <code class="Fn">pthread_setcancelstate</code>() function is + async-signal-safe as required by.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">David + Leonard</span> + <<a class="Mt" href="mailto:d@openbsd.org">d@openbsd.org</a>> for the + <span class="Ux">OpenBSD</span> implementation of + <a class="Xr">pthread_cancel(3)</a>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 18, 2017</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |