original/man3/pthread_sigmask.3

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