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-02-04 "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 CONFORMING TO
  70 POSIX.1-2001.
  71 .SH NOTES
  72 A new thread inherits a copy of its creator's signal mask.
  73 .SH EXAMPLE
  74 The program below blocks some signals in the main thread,
  75 and then creates a dedicated thread to fetch those signals via
  76 .BR sigwait (3).
  77 The following shell session demonstrates its use:
  78
  79 .in +4n
  80 .nf
  81 .RB "$" " ./a.out &"
  82 [1] 5423
  83 .RB "$" " kill \-QUIT %1"
  84 Signal handling thread got signal 3
  85 .RB "$" " kill \-USR1 %1"
  86 Signal handling thread got signal 10
  87 .RB "$" " kill \-TERM %1"
  88 [1]+  Terminated              ./a.out
  89 .fi
  90 .in
  91 .SS Program source
  92 \&
  93 .nf
  94 #include <pthread.h>
  95 #include <stdio.h>
  96 #include <stdlib.h>
  97 #include <unistd.h>
  98 #include <signal.h>
  99 #include <errno.h>
 100
 101 /* Simple error handling functions */
 102
 103 #define handle_error_en(en, msg) \\
 104         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 105
 106 static void *
 107 sig_thread(void *arg)
 108 {
 109     sigset_t *set = arg;
 110     int s, sig;
 111
 112     for (;;) {
 113         s = sigwait(set, &sig);
 114         if (s != 0)
 115             handle_error_en(s, "sigwait");
 116         printf("Signal handling thread got signal %d\\n", sig);
 117     }
 118 }
 119
 120 int
 121 main(int argc, char *argv[])
 122 {
 123     pthread_t thread;
 124     sigset_t set;
 125     int s;
 126
 127     /* Block SIGQUIT and SIGUSR1; other threads created by main()
 128        will inherit a copy of the signal mask. */
 129
 130     sigemptyset(&set);
 131     sigaddset(&set, SIGQUIT);
 132     sigaddset(&set, SIGUSR1);
 133     s = pthread_sigmask(SIG_BLOCK, &set, NULL);
 134     if (s != 0)
 135         handle_error_en(s, "pthread_sigmask");
 136
 137     s = pthread_create(&thread, NULL, &sig_thread, (void *) &set);
 138     if (s != 0)
 139         handle_error_en(s, "pthread_create");
 140
 141     /* Main thread carries on to create other threads and/or do
 142        other work */
 143
 144     pause();            /* Dummy pause so we can test program */
 145 }
 146 .fi
 147 .SH SEE ALSO
 148 .BR sigaction (2),
 149 .BR sigpending (2),
 150 .BR sigprocmask (2),
 151 .BR pthread_create (3),
 152 .BR pthread_kill (3),
 153 .BR sigsetops (3),
 154 .BR pthreads (7),
 155 .BR signal (7)
 156 .SH COLOPHON
 157 This page is part of release 3.64 of the Linux
 158 .I man-pages
 159 project.
 160 A description of the project,
 161 and information about reporting bugs,
 162 can be found at
 163 \%http://www.kernel.org/doc/man\-pages/.