man3/pthread_cleanup_push_defer_np.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_CLEANUP_PUSH_DEFER_NP 3 2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop
   9 thread cancelation clean-up handlers while saving cancelability type
  10 .SH LIBRARY
  11 POSIX threads library
  12 .RI ( libpthread ", " \-lpthread )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <pthread.h>
  16 .PP
  17 .BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg );
  18 .BI "void pthread_cleanup_pop_restore_np(int " execute );
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  26 .BR pthread_cleanup_push_defer_np (),
  27 .BR pthread_cleanup_pop_defer_np ():
  28 .nf
  29     _GNU_SOURCE
  30 .fi
  31 .SH DESCRIPTION
  32 These functions are the same as
  33 .BR pthread_cleanup_push (3)
  34 and
  35 .BR pthread_cleanup_pop (3),
  36 except for the differences noted on this page.
  37 .PP
  38 Like
  39 .BR pthread_cleanup_push (3),
  40 .BR pthread_cleanup_push_defer_np ()
  41 pushes
  42 .I routine
  43 onto the thread's stack of cancelation clean-up handlers.
  44 In addition, it also saves the thread's current cancelability type,
  45 and sets the cancelability type to "deferred" (see
  46 .BR pthread_setcanceltype (3));
  47 this ensures that cancelation clean-up will occur
  48 even if the thread's cancelability type was "asynchronous"
  49 before the call.
  50 .PP
  51 Like
  52 .BR pthread_cleanup_pop (3),
  53 .BR pthread_cleanup_pop_restore_np ()
  54 pops the top-most clean-up handler from the thread's
  55 stack of cancelation clean-up handlers.
  56 In addition, it restores the thread's cancelability
  57 type to its value at the time of the matching
  58 .BR pthread_cleanup_push_defer_np ().
  59 .PP
  60 The caller must ensure that calls to these
  61 functions are paired within the same function,
  62 and at the same lexical nesting level.
  63 Other restrictions apply, as described in
  64 .BR pthread_cleanup_push (3).
  65 .PP
  66 This sequence of calls:
  67 .PP
  68 .in +4n
  69 .EX
  70 pthread_cleanup_push_defer_np(routine, arg);
  71 pthread_cleanup_pop_restore_np(execute);
  72 .EE
  73 .in
  74 .PP
  75 is equivalent to (but shorter and more efficient than):
  76 .PP
  77 .\" As far as I can see, LinuxThreads reverses the two substeps
  78 .\" in the push and pop below.
  79 .in +4n
  80 .EX
  81 int oldtype;
  82
  83 pthread_cleanup_push(routine, arg);
  84 pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
  85 \&...
  86 pthread_setcanceltype(oldtype, NULL);
  87 pthread_cleanup_pop(execute);
  88 .EE
  89 .in
  90 .\" SH VERSIONS
  91 .\" Available since glibc 2.0
  92 .SH STANDARDS
  93 These functions are nonstandard GNU extensions;
  94 hence the suffix "_np" (nonportable) in the names.
  95 .SH SEE ALSO
  96 .BR pthread_cancel (3),
  97 .BR pthread_cleanup_push (3),
  98 .BR pthread_setcancelstate (3),
  99 .BR pthread_testcancel (3),
 100 .BR pthreads (7)