man3/pthread_sigmask.3

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH PTHREAD_SIGMASK 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 pthread_sigmask \- examine and change mask of blocked signals
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <signal.h>
  32 .PP
  33 .BI "int pthread_sigmask(int " how ", const sigset_t *" set \
  34 ", sigset_t *" oldset );
  35 .fi
  36 .PP
  37 Compile and link with \fI\-pthread\fP.
  38 .PP
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .PP
  44 .BR pthread_sigmask ():
  45 .nf
  46     _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
  47 .fi
  48 .SH DESCRIPTION
  49 The
  50 .BR pthread_sigmask ()
  51 function is just like
  52 .BR sigprocmask (2),
  53 with the difference that its use in multithreaded programs
  54 is explicitly specified by POSIX.1.
  55 Other differences are noted in this page.
  56 .PP
  57 For a description of the arguments and operation of this function, see
  58 .BR sigprocmask (2).
  59 .SH RETURN VALUE
  60 On success,
  61 .BR pthread_sigmask ()
  62 returns 0;
  63 on error, it returns an error number.
  64 .SH ERRORS
  65 See
  66 .BR sigprocmask (2).
  67 .SH ATTRIBUTES
  68 For an explanation of the terms used in this section, see
  69 .BR attributes (7).
  70 .ad l
  71 .nh
  72 .TS
  73 allbox;
  74 lbx lb lb
  75 l l l.
  76 Interface       Attribute       Value
  77 T{
  78 .BR pthread_sigmask ()
  79 T}      Thread safety   MT-Safe
  80 .TE
  81 .hy
  82 .ad
  83 .sp 1
  84 .SH CONFORMING TO
  85 POSIX.1-2001, POSIX.1-2008.
  86 .SH NOTES
  87 A new thread inherits a copy of its creator's signal mask.
  88 .PP
  89 The glibc
  90 .BR pthread_sigmask ()
  91 function silently ignores attempts to block the two real-time signals that
  92 are used internally by the NPTL threading implementation.
  93 See
  94 .BR nptl (7)
  95 for details.
  96 .SH EXAMPLES
  97 The program below blocks some signals in the main thread,
  98 and then creates a dedicated thread to fetch those signals via
  99 .BR sigwait (3).
 100 The following shell session demonstrates its use:
 101 .PP
 102 .in +4n
 103 .EX
 104 .RB "$" " ./a.out &"
 105 [1] 5423
 106 .RB "$" " kill \-QUIT %1"
 107 Signal handling thread got signal 3
 108 .RB "$" " kill \-USR1 %1"
 109 Signal handling thread got signal 10
 110 .RB "$" " kill \-TERM %1"
 111 [1]+  Terminated              ./a.out
 112 .EE
 113 .in
 114 .SS Program source
 115 \&
 116 .EX
 117 #include <pthread.h>
 118 #include <stdio.h>
 119 #include <stdlib.h>
 120 #include <unistd.h>
 121 #include <signal.h>
 122 #include <errno.h>
 123
 124 /* Simple error handling functions */
 125
 126 #define handle_error_en(en, msg) \e
 127         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 128
 129 static void *
 130 sig_thread(void *arg)
 131 {
 132     sigset_t *set = arg;
 133     int s, sig;
 134
 135     for (;;) {
 136         s = sigwait(set, &sig);
 137         if (s != 0)
 138             handle_error_en(s, "sigwait");
 139         printf("Signal handling thread got signal %d\en", sig);
 140     }
 141 }
 142
 143 int
 144 main(int argc, char *argv[])
 145 {
 146     pthread_t thread;
 147     sigset_t set;
 148     int s;
 149
 150     /* Block SIGQUIT and SIGUSR1; other threads created by main()
 151        will inherit a copy of the signal mask. */
 152
 153     sigemptyset(&set);
 154     sigaddset(&set, SIGQUIT);
 155     sigaddset(&set, SIGUSR1);
 156     s = pthread_sigmask(SIG_BLOCK, &set, NULL);
 157     if (s != 0)
 158         handle_error_en(s, "pthread_sigmask");
 159
 160     s = pthread_create(&thread, NULL, &sig_thread, &set);
 161     if (s != 0)
 162         handle_error_en(s, "pthread_create");
 163
 164     /* Main thread carries on to create other threads and/or do
 165        other work. */
 166
 167     pause();            /* Dummy pause so we can test program */
 168 }
 169 .EE
 170 .SH SEE ALSO
 171 .BR sigaction (2),
 172 .BR sigpending (2),
 173 .BR sigprocmask (2),
 174 .BR pthread_attr_setsigmask_np (3),
 175 .BR pthread_create (3),
 176 .BR pthread_kill (3),
 177 .BR sigsetops (3),
 178 .BR pthreads (7),
 179 .BR signal (7)