Movatterモバイル変換

pthread_cancel(3) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|ATTRIBUTES \|VERSIONS \|STANDARDS \|HISTORY \|EXAMPLES \|SEE ALSO \|COLOPHON

pthread_cancel(3)        Library Functions Manualpthread_cancel(3)

NAME top

       pthread_cancel - send a cancelation request to a thread

LIBRARY top

       POSIX threads library (libpthread,-lpthread)

SYNOPSIS top

#include <pthread.h>int pthread_cancel(pthread_tthread);

DESCRIPTION top

       Thepthread_cancel() function sends a cancelation request to the       threadthread.  Whether and when the target thread reacts to the       cancelation request depends on two attributes that are under the       control of that thread: its cancelabilitystate andtype.       A thread's cancelability state, determined bypthread_setcancelstate(3), can beenabled (the default for new       threads) ordisabled.  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.       A thread's cancelation type, determined bypthread_setcanceltype(3), may be eitherasynchronous ordeferred       (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 acancelation point.  A list of functions that       are or may be cancelation points is provided inpthreads(7).       When a cancelation request is acted on, the following steps occur       forthread (in this order):       (1)  Cancelation clean-up handlers are popped (in the reverse of            the order in which they were pushed) and called.  (Seepthread_cleanup_push(3).)       (2)  Thread-specific data destructors are called, in an            unspecified order.  (Seepthread_key_create(3).)       (3)  The thread is terminated.  (Seepthread_exit(3).)       The above steps happen asynchronously with respect to thepthread_cancel() call; the return status ofpthread_cancel()       merely informs the caller whether the cancelation request was       successfully queued.       After a canceled thread has terminated, a join with that thread       usingpthread_join(3) obtainsPTHREAD_CANCELEDas the thread's       exit status.  (Joining with a thread is the only way to know that       cancelation has completed.)

RETURN VALUE top

       On success,pthread_cancel() returns 0; on error, it returns a       nonzero error number.

ERRORS top

ESRCHNo thread with the IDthread could be found.

ATTRIBUTES top

       For an explanation of the terms used in this section, seeattributes(7).       ┌──────────────────────────────────────┬───────────────┬─────────┐       │Interface│Attribute│Value│       ├──────────────────────────────────────┼───────────────┼─────────┤       │pthread_cancel()                     │ Thread safety │ MT-Safe │       └──────────────────────────────────────┴───────────────┴─────────┘

VERSIONS top

       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,       otherwiseSIGUSR2is used.

STANDARDS top

       POSIX.1-2008.

HISTORY top

       glibc 2.0 POSIX.1-2001.

EXAMPLES top

       The program below creates a thread and then cancels it.  The main       thread joins with the canceled thread to check that its exit       status wasPTHREAD_CANCELED.  The following shell session shows       what happens when we run the program:           $ ./a.out           thread_func(): started; cancelation disabled           main(): sending cancelation request           thread_func(): about to enable cancelation           main(): thread was canceledProgram source       #include <errno.h>       #include <pthread.h>       #include <stdio.h>       #include <stdlib.h>       #include <unistd.h>       #define handle_error_en(en, msg) \               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'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\n", __func__);           sleep(5);           printf("%s(): about to enable cancelation\n", __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!\n", __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\n", __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\n", __func__);           else               printf("%s(): thread wasn't canceled (shouldn't happen!)\n",                      __func__);           exit(EXIT_SUCCESS);       }

COLOPHON top

       This page is part of theman-pages (Linux kernel and C library       user-space interface documentation) project.  Information about       the project can be found at        ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report       for this manual page, see       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.       This page was obtained from the tarball man-pages-6.15.tar.gz       fetched from       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on       2025-08-11.  If you discover any rendering problems in this HTML       version of the page, or you believe there is a better or more up-       to-date source for the page, or you have corrections or       improvements to the information in this COLOPHON (which isnot       part of the original manual page), send a mail to       man-pages@man7.orgLinux man-pages 6.15            2025-05-17pthread_cancel(3)

Pages that refer to this page:pthread_cleanup_push(3), pthread_cleanup_push_defer_np(3), pthread_create(3), pthread_detach(3), pthread_join(3), pthread_kill_other_threads_np(3), pthread_mutex_init(3), pthread_setcancelstate(3), pthread_testcancel(3), pthreads(7)