diff options
Diffstat (limited to 'man3/pthread_cancel.3')
| -rw-r--r-- | man3/pthread_cancel.3 | 237 |
1 files changed, 0 insertions, 237 deletions
diff --git a/man3/pthread_cancel.3 b/man3/pthread_cancel.3 deleted file mode 100644 index 3fef2f1c5..000000000 --- a/man3/pthread_cancel.3 +++ /dev/null @@ -1,237 +0,0 @@ -'\" 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) |