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 2019-03-06 "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 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .PP
  44 .ad l
  45 .BR pthread_sigmask ():
  46 .RS 4
  47 _POSIX_C_SOURCE\ >=\ 199506L || _XOPEN_SOURCE\ >=\ 500
  48 .RE
  49 .ad b
  50 .SH DESCRIPTION
  51 The
  52 .BR pthread_sigmask ()
  53 function is just like
  54 .BR sigprocmask (2),
  55 with the difference that its use in multithreaded programs
  56 is explicitly specified by POSIX.1.
  57 Other differences are noted in this page.
  58 .PP
  59 For a description of the arguments and operation of this function, see
  60 .BR sigprocmask (2).
  61 .SH RETURN VALUE
  62 On success,
  63 .BR pthread_sigmask ()
  64 returns 0;
  65 on error, it returns an error number.
  66 .SH ERRORS
  67 See
  68 .BR sigprocmask (2).
  69 .SH ATTRIBUTES
  70 For an explanation of the terms used in this section, see
  71 .BR attributes (7).
  72 .TS
  73 allbox;
  74 lb 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 .SH CONFORMING TO
  82 POSIX.1-2001, POSIX.1-2008.
  83 .SH NOTES
  84 A new thread inherits a copy of its creator's signal mask.
  85 .PP
  86 The glibc
  87 .BR pthread_sigmask ()
  88 function silently ignores attempts to block the two real-time signals that
  89 are used internally by the NPTL threading implementation.
  90 See
  91 .BR nptl (7)
  92 for details.
  93 .SH EXAMPLE
  94 The program below blocks some signals in the main thread,
  95 and then creates a dedicated thread to fetch those signals via
  96 .BR sigwait (3).
  97 The following shell session demonstrates its use:
  98 .PP
  99 .in +4n
 100 .EX
 101 .RB "$" " ./a.out &"
 102 [1] 5423
 103 .RB "$" " kill \-QUIT %1"
 104 Signal handling thread got signal 3
 105 .RB "$" " kill \-USR1 %1"
 106 Signal handling thread got signal 10
 107 .RB "$" " kill \-TERM %1"
 108 [1]+  Terminated              ./a.out
 109 .EE
 110 .in
 111 .SS Program source
 112 \&
 113 .EX
 114 #include <pthread.h>
 115 #include <stdio.h>
 116 #include <stdlib.h>
 117 #include <unistd.h>
 118 #include <signal.h>
 119 #include <errno.h>
 120
 121 /* Simple error handling functions */
 122
 123 #define handle_error_en(en, msg) \e
 124         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 125
 126 static void *
 127 sig_thread(void *arg)
 128 {
 129     sigset_t *set = arg;
 130     int s, sig;
 131
 132     for (;;) {
 133         s = sigwait(set, &sig);
 134         if (s != 0)
 135             handle_error_en(s, "sigwait");
 136         printf("Signal handling thread got signal %d\en", sig);
 137     }
 138 }
 139
 140 int
 141 main(int argc, char *argv[])
 142 {
 143     pthread_t thread;
 144     sigset_t set;
 145     int s;
 146
 147     /* Block SIGQUIT and SIGUSR1; other threads created by main()
 148        will inherit a copy of the signal mask. */
 149
 150     sigemptyset(&set);
 151     sigaddset(&set, SIGQUIT);
 152     sigaddset(&set, SIGUSR1);
 153     s = pthread_sigmask(SIG_BLOCK, &set, NULL);
 154     if (s != 0)
 155         handle_error_en(s, "pthread_sigmask");
 156
 157     s = pthread_create(&thread, NULL, &sig_thread, (void *) &set);
 158     if (s != 0)
 159         handle_error_en(s, "pthread_create");
 160
 161     /* Main thread carries on to create other threads and/or do
 162        other work */
 163
 164     pause();            /* Dummy pause so we can test program */
 165 }
 166 .EE
 167 .SH SEE ALSO
 168 .BR sigaction (2),
 169 .BR sigpending (2),
 170 .BR sigprocmask (2),
 171 .BR pthread_create (3),
 172 .BR pthread_kill (3),
 173 .BR sigsetops (3),
 174 .BR pthreads (7),
 175 .BR signal (7)