original/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 2014-05-19 "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
  33 .BI "int pthread_sigmask(int " how ", const sigset_t *" set \
  34 ", sigset_t *" oldset );
  35 .fi
  36 .sp
  37 Compile and link with \fI\-pthread\fP.
  38 .sp
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .sp
  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-2001.
  57 Other differences are noted in this page.
  58
  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 .SS Multithreading (see pthreads(7))
  71 The
  72 .BR pthread_sigmask ()
  73 function is thread-safe.
  74 .SH CONFORMING TO
  75 POSIX.1-2001.
  76 .SH NOTES
  77 A new thread inherits a copy of its creator's signal mask.
  78 .SH EXAMPLE
  79 The program below blocks some signals in the main thread,
  80 and then creates a dedicated thread to fetch those signals via
  81 .BR sigwait (3).
  82 The following shell session demonstrates its use:
  83
  84 .in +4n
  85 .nf
  86 .RB "$" " ./a.out &"
  87 [1] 5423
  88 .RB "$" " kill \-QUIT %1"
  89 Signal handling thread got signal 3
  90 .RB "$" " kill \-USR1 %1"
  91 Signal handling thread got signal 10
  92 .RB "$" " kill \-TERM %1"
  93 [1]+  Terminated              ./a.out
  94 .fi
  95 .in
  96 .SS Program source
  97 \&
  98 .nf
  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) \\
 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\\n", 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, (void *) &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 .fi
 152 .SH SEE ALSO
 153 .BR sigaction (2),
 154 .BR sigpending (2),
 155 .BR sigprocmask (2),
 156 .BR pthread_create (3),
 157 .BR pthread_kill (3),
 158 .BR sigsetops (3),
 159 .BR pthreads (7),
 160 .BR signal (7)
 161 .SH COLOPHON
 162 This page is part of release 3.79 of the Linux
 163 .I man-pages
 164 project.
 165 A description of the project,
 166 information about reporting bugs,
 167 and the latest version of this page,
 168 can be found at
 169 \%http://www.kernel.org/doc/man\-pages/.