man2/sigprocmask.2

   1 .\" Copyright (c) 2005 Michael Kerrisk
   2 .\" based on earlier work by faith@cs.unc.edu and
   3 .\" Mike Battersby <mib@deakin.edu.au>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2
   8 .\"
   9 .TH sigprocmask 2 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 sigprocmask, rt_sigprocmask \- examine and change blocked signals
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .B #include <signal.h>
  17 .P
  18 .nf
  19 /* Prototype for the glibc wrapper function */
  20 .BI "int sigprocmask(int " how ", const sigset_t *_Nullable restrict " set ,
  21 .BI "                           sigset_t *_Nullable restrict " oldset );
  22 .P
  23 .BR "#include <signal.h>" "           /* Definition of " SIG_* " constants */"
  24 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  25 .B #include <unistd.h>
  26 .P
  27 /* Prototype for the underlying system call */
  28 .BI "int syscall(SYS_rt_sigprocmask, int " how ,
  29 .BI "                           const kernel_sigset_t *_Nullable " set ,
  30 .BI "                           kernel_sigset_t *_Nullable " oldset ,
  31 .BI "                           size_t " sigsetsize );
  32 .P
  33 /* Prototype for the legacy system call */
  34 .BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how ,
  35 .BI "                           const old_kernel_sigset_t *_Nullable " set ,
  36 .BI "                           old_kernel_sigset_t *_Nullable " oldset );
  37 .fi
  38 .P
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .P
  44 .BR sigprocmask ():
  45 .nf
  46     _POSIX_C_SOURCE
  47 .fi
  48 .SH DESCRIPTION
  49 .BR sigprocmask ()
  50 is used to fetch and/or change the signal mask of the calling thread.
  51 The signal mask is the set of signals whose delivery is currently
  52 blocked for the caller
  53 (see also
  54 .BR signal (7)
  55 for more details).
  56 .P
  57 The behavior of the call is dependent on the value of
  58 .IR how ,
  59 as follows.
  60 .TP
  61 .B SIG_BLOCK
  62 The set of blocked signals is the union of the current set and the
  63 .I set
  64 argument.
  65 .TP
  66 .B SIG_UNBLOCK
  67 The signals in
  68 .I set
  69 are removed from the current set of blocked signals.
  70 It is permissible to attempt to unblock a signal which is not blocked.
  71 .TP
  72 .B SIG_SETMASK
  73 The set of blocked signals is set to the argument
  74 .IR set .
  75 .P
  76 If
  77 .I oldset
  78 is non-NULL, the previous value of the signal mask is stored in
  79 .IR oldset .
  80 .P
  81 If
  82 .I set
  83 is NULL, then the signal mask is unchanged (i.e.,
  84 .I how
  85 is ignored),
  86 but the current value of the signal mask is nevertheless returned in
  87 .I oldset
  88 (if it is not NULL).
  89 .P
  90 A set of functions for modifying and inspecting variables of type
  91 .I sigset_t
  92 ("signal sets") is described in
  93 .BR sigsetops (3).
  94 .P
  95 The use of
  96 .BR sigprocmask ()
  97 is unspecified in a multithreaded process; see
  98 .BR pthread_sigmask (3).
  99 .SH RETURN VALUE
 100 .BR sigprocmask ()
 101 returns 0 on success.
 102 On failure, \-1 is returned and
 103 .I errno
 104 is set to indicate the error.
 105 .SH ERRORS
 106 .TP
 107 .B EFAULT
 108 The
 109 .I set
 110 or
 111 .I oldset
 112 argument points outside the process's allocated address space.
 113 .TP
 114 .B EINVAL
 115 Either the value specified in
 116 .I how
 117 was invalid or the kernel does not support the size passed in
 118 .I sigsetsize.
 119 .SH VERSIONS
 120 .SS C library/kernel differences
 121 The kernel's definition of
 122 .I sigset_t
 123 differs in size from that used
 124 by the C library.
 125 In this manual page, the former is referred to as
 126 .I kernel_sigset_t
 127 (it is nevertheless named
 128 .I sigset_t
 129 in the kernel sources).
 130 .P
 131 The glibc wrapper function for
 132 .BR sigprocmask ()
 133 silently ignores attempts to block the two real-time signals that
 134 are used internally by the NPTL threading implementation.
 135 See
 136 .BR nptl (7)
 137 for details.
 138 .P
 139 The original Linux system call was named
 140 .BR sigprocmask ().
 141 However, with the addition of real-time signals in Linux 2.2,
 142 the fixed-size, 32-bit
 143 .I sigset_t
 144 (referred to as
 145 .I old_kernel_sigset_t
 146 in this manual page)
 147 type supported by that system call was no longer fit for purpose.
 148 Consequently, a new system call,
 149 .BR rt_sigprocmask (),
 150 was added to support an enlarged
 151 .I sigset_t
 152 type
 153 (referred to as
 154 .I kernel_sigset_t
 155 in this manual page).
 156 The new system call takes a fourth argument,
 157 .IR "size_t sigsetsize" ,
 158 which specifies the size in bytes of the signal sets in
 159 .I set
 160 and
 161 .IR oldset .
 162 This argument is currently required to have a fixed architecture specific value
 163 (equal to
 164 .IR sizeof(kernel_sigset_t) ).
 165 .\" sizeof(kernel_sigset_t) == _NSIG / 8,
 166 .\" which equals to 8 on most architectures, but e.g. on MIPS it's 16.
 167 .P
 168 The glibc
 169 .BR sigprocmask ()
 170 wrapper function hides these details from us, transparently calling
 171 .BR rt_sigprocmask ()
 172 when the kernel provides it.
 173 .\"
 174 .SH STANDARDS
 175 POSIX.1-2008.
 176 .SH HISTORY
 177 POSIX.1-2001.
 178 .SH NOTES
 179 It is not possible to block
 180 .BR SIGKILL " or " SIGSTOP .
 181 Attempts to do so are silently ignored.
 182 .P
 183 Each of the threads in a process has its own signal mask.
 184 .P
 185 A child created via
 186 .BR fork (2)
 187 inherits a copy of its parent's signal mask;
 188 the signal mask is preserved across
 189 .BR execve (2).
 190 .P
 191 If
 192 .BR SIGBUS ,
 193 .BR SIGFPE ,
 194 .BR SIGILL ,
 195 or
 196 .B SIGSEGV
 197 are generated
 198 while they are blocked, the result is undefined,
 199 unless the signal was generated by
 200 .BR kill (2),
 201 .BR sigqueue (3),
 202 or
 203 .BR raise (3).
 204 .P
 205 See
 206 .BR sigsetops (3)
 207 for details on manipulating signal sets.
 208 .P
 209 Note that it is permissible (although not very useful) to specify both
 210 .I set
 211 and
 212 .I oldset
 213 as NULL.
 214 .SH SEE ALSO
 215 .BR kill (2),
 216 .BR pause (2),
 217 .BR sigaction (2),
 218 .BR signal (2),
 219 .BR sigpending (2),
 220 .BR sigsuspend (2),
 221 .BR pthread_sigmask (3),
 222 .BR sigqueue (3),
 223 .BR sigsetops (3),
 224 .BR signal (7)