diff options
Diffstat (limited to 'man/man3/pthread_cancel.3')
| -rw-r--r-- | man/man3/pthread_cancel.3 | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/man/man3/pthread_cancel.3 b/man/man3/pthread_cancel.3 new file mode 100644 index 000000000..3fef2f1c5 --- /dev/null +++ b/man/man3/pthread_cancel.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cancel 3 (date) "Linux man-pages (unreleased)" +.SH NAME +pthread_cancel \- send a cancelation request to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.P +.BI "int pthread_cancel(pthread_t " thread ); +.fi +.SH DESCRIPTION +The +.BR pthread_cancel () +function sends a cancelation request to the thread +.IR thread . +Whether and when the target thread +reacts to the cancelation request depends on +two attributes that are under the control of that thread: +its cancelability +.I state +and +.IR type . +.P +A thread's cancelability state, determined by +.BR pthread_setcancelstate (3), +can be +.I enabled +(the default for new threads) or +.IR disabled . +If a thread has disabled cancelation, +then a cancelation request remains queued until the thread +enables cancelation. +If a thread has enabled cancelation, +then its cancelability type determines when cancelation occurs. +.P +A thread's cancelation type, determined by +.BR pthread_setcanceltype (3), +may be either +.I asynchronous +or +.I deferred +(the default for new threads). +Asynchronous cancelability +means that the thread can be canceled at any time +(usually immediately, but the system does not guarantee this). +Deferred cancelability means that cancelation will be delayed until +the thread next calls a function that is a +.IR "cancelation point" . +A list of functions that are or may be cancelation points is provided in +.BR pthreads (7). +.P +When a cancelation requested is acted on, the following steps occur for +.I thread +(in this order): +.IP (1) 5 +Cancelation clean-up handlers are popped +(in the reverse of the order in which they were pushed) and called. +(See +.BR pthread_cleanup_push (3).) +.IP (2) +Thread-specific data destructors are called, +in an unspecified order. +(See +.BR pthread_key_create (3).) +.IP (3) +The thread is terminated. +(See +.BR pthread_exit (3).) +.P +The above steps happen asynchronously with respect to the +.BR pthread_cancel () +call; +the return status of +.BR pthread_cancel () +merely informs the caller whether the cancelation request +was successfully queued. +.P +After a canceled thread has terminated, +a join with that thread using +.BR pthread_join (3) +obtains +.B PTHREAD_CANCELED +as the thread's exit status. +(Joining with a thread is the only way to know that cancelation +has completed.) +.SH RETURN VALUE +On success, +.BR pthread_cancel () +returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_cancel () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, cancelation is implemented using signals. +Under the NPTL threading implementation, +the first real-time signal (i.e., signal 32) is used for this purpose. +On LinuxThreads, the second real-time signal is used, +if real-time signals are available, otherwise +.B SIGUSR2 +is used. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH EXAMPLES +The program below creates a thread and then cancels it. +The main thread joins with the canceled thread to check +that its exit status was +.BR PTHREAD_CANCELED . +The following shell session shows what happens when we run the program: +.P +.in +4n +.EX +$ ./a.out +thread_func(): started; cancelation disabled +main(): sending cancelation request +thread_func(): about to enable cancelation +main(): thread was canceled +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_cancel.c) +.EX +#include <errno.h> +#include <pthread.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +thread_func(void *ignored_argument) +{ + int s; +\& + /* Disable cancelation for a while, so that we don\[aq]t + immediately react to a cancelation request. */ +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + printf("%s(): started; cancelation disabled\en", __func__); + sleep(5); + printf("%s(): about to enable cancelation\en", __func__); +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + /* sleep() is a cancelation point. */ +\& + sleep(1000); /* Should get canceled while we sleep */ +\& + /* Should never get here. */ +\& + printf("%s(): not canceled!\en", __func__); + return NULL; +} +\& +int +main(void) +{ + pthread_t thr; + void *res; + int s; +\& + /* Start a thread and then send it a cancelation request. */ +\& + s = pthread_create(&thr, NULL, &thread_func, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + sleep(2); /* Give thread a chance to get started */ +\& + printf("%s(): sending cancelation request\en", __func__); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); +\& + /* Join with thread to see what its exit status was. */ +\& + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + if (res == PTHREAD_CANCELED) + printf("%s(): thread was canceled\en", __func__); + else + printf("%s(): thread wasn\[aq]t canceled (shouldn\[aq]t happen!)\en", + __func__); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_cleanup_push (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthread_key_create (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_testcancel (3), +.BR pthreads (7) |