man3/pthread_sigmask.3

   1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH PTHREAD_SIGMASK 3 2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 pthread_sigmask \- examine and change mask of blocked signals
   9 .SH LIBRARY
  10 POSIX threads library
  11 .RI ( libpthread ", " \-lpthread )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <signal.h>
  15 .PP
  16 .BI "int pthread_sigmask(int " how ", const sigset_t *" set \
  17 ", sigset_t *" oldset );
  18 .fi
  19 .PP
  20 .RS -4
  21 Feature Test Macro Requirements for glibc (see
  22 .BR feature_test_macros (7)):
  23 .RE
  24 .PP
  25 .BR pthread_sigmask ():
  26 .nf
  27     _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
  28 .fi
  29 .SH DESCRIPTION
  30 The
  31 .BR pthread_sigmask ()
  32 function is just like
  33 .BR sigprocmask (2),
  34 with the difference that its use in multithreaded programs
  35 is explicitly specified by POSIX.1.
  36 Other differences are noted in this page.
  37 .PP
  38 For a description of the arguments and operation of this function, see
  39 .BR sigprocmask (2).
  40 .SH RETURN VALUE
  41 On success,
  42 .BR pthread_sigmask ()
  43 returns 0;
  44 on error, it returns an error number.
  45 .SH ERRORS
  46 See
  47 .BR sigprocmask (2).
  48 .SH ATTRIBUTES
  49 For an explanation of the terms used in this section, see
  50 .BR attributes (7).
  51 .ad l
  52 .nh
  53 .TS
  54 allbox;
  55 lbx lb lb
  56 l l l.
  57 Interface       Attribute       Value
  58 T{
  59 .BR pthread_sigmask ()
  60 T}      Thread safety   MT-Safe
  61 .TE
  62 .hy
  63 .ad
  64 .sp 1
  65 .SH STANDARDS
  66 POSIX.1-2001, POSIX.1-2008.
  67 .SH NOTES
  68 A new thread inherits a copy of its creator's signal mask.
  69 .PP
  70 The glibc
  71 .BR pthread_sigmask ()
  72 function silently ignores attempts to block the two real-time signals that
  73 are used internally by the NPTL threading implementation.
  74 See
  75 .BR nptl (7)
  76 for details.
  77 .SH EXAMPLES
  78 The program below blocks some signals in the main thread,
  79 and then creates a dedicated thread to fetch those signals via
  80 .BR sigwait (3).
  81 The following shell session demonstrates its use:
  82 .PP
  83 .in +4n
  84 .EX
  85 .RB "$" " ./a.out &"
  86 [1] 5423
  87 .RB "$" " kill \-QUIT %1"
  88 Signal handling thread got signal 3
  89 .RB "$" " kill \-USR1 %1"
  90 Signal handling thread got signal 10
  91 .RB "$" " kill \-TERM %1"
  92 [1]+  Terminated              ./a.out
  93 .EE
  94 .in
  95 .SS Program source
  96 \&
  97 .\" SRC BEGIN (pthread_sigmask.c)
  98 .EX
  99 #include <pthread.h>
 100 #include <stdio.h>
 101 #include <stdlib.h>
 102 #include <unistd.h>
 103 #include <signal.h>
 104 #include <errno.h>
 105
 106 /* Simple error handling functions */
 107
 108 #define handle_error_en(en, msg) \e
 109         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 110
 111 static void *
 112 sig_thread(void *arg)
 113 {
 114     sigset_t *set = arg;
 115     int s, sig;
 116
 117     for (;;) {
 118         s = sigwait(set, &sig);
 119         if (s != 0)
 120             handle_error_en(s, "sigwait");
 121         printf("Signal handling thread got signal %d\en", sig);
 122     }
 123 }
 124
 125 int
 126 main(int argc, char *argv[])
 127 {
 128     pthread_t thread;
 129     sigset_t set;
 130     int s;
 131
 132     /* Block SIGQUIT and SIGUSR1; other threads created by main()
 133        will inherit a copy of the signal mask. */
 134
 135     sigemptyset(&set);
 136     sigaddset(&set, SIGQUIT);
 137     sigaddset(&set, SIGUSR1);
 138     s = pthread_sigmask(SIG_BLOCK, &set, NULL);
 139     if (s != 0)
 140         handle_error_en(s, "pthread_sigmask");
 141
 142     s = pthread_create(&thread, NULL, &sig_thread, &set);
 143     if (s != 0)
 144         handle_error_en(s, "pthread_create");
 145
 146     /* Main thread carries on to create other threads and/or do
 147        other work. */
 148
 149     pause();            /* Dummy pause so we can test program */
 150 }
 151 .EE
 152 .\" SRC END
 153 .SH SEE ALSO
 154 .BR sigaction (2),
 155 .BR sigpending (2),
 156 .BR sigprocmask (2),
 157 .BR pthread_attr_setsigmask_np (3),
 158 .BR pthread_create (3),
 159 .BR pthread_kill (3),
 160 .BR sigsetops (3),
 161 .BR pthreads (7),
 162 .BR signal (7)