man3/sigvec.3

   1 .\" Copyright (c) 2005 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH sigvec 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <signal.h>
  14 .PP
  15 .BI "int sigvec(int " sig ", const struct sigvec *" vec ", struct sigvec *" ovec );
  16 .PP
  17 .BI "int sigmask(int " signum );
  18 .PP
  19 .BI "int sigblock(int " mask );
  20 .BI "int sigsetmask(int " mask );
  21 .B int siggetmask(void);
  22 .fi
  23 .PP
  24 .RS -4
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .RE
  28 .PP
  29 All functions shown above:
  30 .nf
  31     Since glibc 2.19:
  32         _DEFAULT_SOURCE
  33     Glibc 2.19 and earlier:
  34         _BSD_SOURCE
  35 .fi
  36 .SH DESCRIPTION
  37 These functions are provided in glibc as a compatibility interface
  38 for programs that make use of the historical BSD signal API.
  39 This API is obsolete: new applications should use the POSIX signal API
  40 .RB ( sigaction (2),
  41 .BR sigprocmask (2),
  42 etc.).
  43 .PP
  44 The
  45 .BR sigvec ()
  46 function sets and/or gets the disposition of the signal
  47 .I sig
  48 (like the POSIX
  49 .BR sigaction (2)).
  50 If
  51 .I vec
  52 is not NULL, it points to a
  53 .I sigvec
  54 structure that defines the new disposition for
  55 .IR sig .
  56 If
  57 .I ovec
  58 is not NULL, it points to a
  59 .I sigvec
  60 structure that is used to return the previous disposition of
  61 .IR sig .
  62 To obtain the current disposition of
  63 .I sig
  64 without changing it, specify NULL for
  65 .IR vec ,
  66 and a non-null pointer for
  67 .IR ovec .
  68 .PP
  69 The dispositions for
  70 .B SIGKILL
  71 and
  72 .B SIGSTOP
  73 cannot be changed.
  74 .PP
  75 The
  76 .I sigvec
  77 structure has the following form:
  78 .PP
  79 .in +4n
  80 .EX
  81 struct sigvec {
  82     void (*sv_handler)(int); /* Signal disposition */
  83     int    sv_mask;          /* Signals to be blocked in handler */
  84     int    sv_flags;         /* Flags */
  85 };
  86 .EE
  87 .in
  88 .PP
  89 The
  90 .I sv_handler
  91 field specifies the disposition of the signal, and is either:
  92 the address of a signal handler function;
  93 .BR SIG_DFL ,
  94 meaning the default disposition applies for the signal; or
  95 .BR SIG_IGN ,
  96 meaning that the signal is ignored.
  97 .PP
  98 If
  99 .I sv_handler
 100 specifies the address of a signal handler, then
 101 .I sv_mask
 102 specifies a mask of signals that are to be blocked while
 103 the handler is executing.
 104 In addition, the signal for which the handler is invoked is
 105 also blocked.
 106 Attempts to block
 107 .B SIGKILL
 108 or
 109 .B SIGSTOP
 110 are silently ignored.
 111 .PP
 112 If
 113 .I sv_handler
 114 specifies the address of a signal handler, then the
 115 .I sv_flags
 116 field specifies flags controlling what happens when the handler is called.
 117 This field may contain zero or more of the following flags:
 118 .TP
 119 .B SV_INTERRUPT
 120 If the signal handler interrupts a blocking system call,
 121 then upon return from the handler the system call is not restarted:
 122 instead it fails with the error
 123 .BR EINTR .
 124 If this flag is not specified, then system calls are restarted
 125 by default.
 126 .TP
 127 .B SV_RESETHAND
 128 Reset the disposition of the signal to the default
 129 before calling the signal handler.
 130 If this flag is not specified, then the handler remains established
 131 until explicitly removed by a later call to
 132 .BR sigvec ()
 133 or until the process performs an
 134 .BR execve (2).
 135 .TP
 136 .B SV_ONSTACK
 137 Handle the signal on the alternate signal stack
 138 (historically established under BSD using the obsolete
 139 .BR sigstack ()
 140 function; the POSIX replacement is
 141 .BR sigaltstack (2)).
 142 .PP
 143 The
 144 .BR sigmask ()
 145 macro constructs and returns a "signal mask" for
 146 .IR signum .
 147 For example, we can initialize the
 148 .I vec.sv_mask
 149 field given to
 150 .BR sigvec ()
 151 using code such as the following:
 152 .PP
 153 .in +4n
 154 .EX
 155 vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT);
 156             /* Block SIGQUIT and SIGABRT during
 157                handler execution */
 158 .EE
 159 .in
 160 .PP
 161 The
 162 .BR sigblock ()
 163 function adds the signals in
 164 .I mask
 165 to the process's signal mask
 166 (like POSIX
 167 .IR sigprocmask(SIG_BLOCK) ),
 168 and returns the process's previous signal mask.
 169 Attempts to block
 170 .B SIGKILL
 171 or
 172 .B SIGSTOP
 173 are silently ignored.
 174 .PP
 175 The
 176 .BR sigsetmask ()
 177 function sets the process's signal mask to the value given in
 178 .I mask
 179 (like POSIX
 180 .IR sigprocmask(SIG_SETMASK) ),
 181 and returns the process's previous signal mask.
 182 .PP
 183 The
 184 .BR siggetmask ()
 185 function returns the process's current signal mask.
 186 This call is equivalent to
 187 .IR sigblock(0) .
 188 .SH RETURN VALUE
 189 The
 190 .BR sigvec ()
 191 function returns 0 on success; on error, it returns \-1 and sets
 192 .I errno
 193 to indicate the error.
 194 .PP
 195 The
 196 .BR sigblock ()
 197 and
 198 .BR sigsetmask ()
 199 functions return the previous signal mask.
 200 .PP
 201 The
 202 .BR sigmask ()
 203 macro returns the signal mask for
 204 .IR signum .
 205 .SH ERRORS
 206 See the ERRORS under
 207 .BR sigaction (2)
 208 and
 209 .BR sigprocmask (2).
 210 .SH VERSIONS
 211 Starting with version 2.21, the GNU C library no longer exports the
 212 .BR sigvec ()
 213 function as part of the ABI.
 214 (To ensure backward compatibility,
 215 the glibc symbol versioning scheme continues to export the interface
 216 to binaries linked against older versions of the library.)
 217 .SH ATTRIBUTES
 218 For an explanation of the terms used in this section, see
 219 .BR attributes (7).
 220 .ad l
 221 .nh
 222 .TS
 223 allbox;
 224 lbx lb lb
 225 l l l.
 226 Interface       Attribute       Value
 227 T{
 228 .BR sigvec (),
 229 .BR sigmask (),
 230 .BR sigblock (),
 231 .BR sigsetmask (),
 232 .BR siggetmask ()
 233 T}      Thread safety   MT-Safe
 234 .TE
 235 .hy
 236 .ad
 237 .sp 1
 238 .SH STANDARDS
 239 All of these functions were in
 240 4.3BSD, except
 241 .BR siggetmask (),
 242 whose origin is unclear.
 243 These functions are obsolete: do not use them in new programs.
 244 .SH NOTES
 245 On 4.3BSD, the
 246 .BR signal ()
 247 function provided reliable semantics (as when calling
 248 .BR sigvec ()
 249 with
 250 .I vec.sv_mask
 251 equal to 0).
 252 On System V,
 253 .BR signal ()
 254 provides unreliable semantics.
 255 POSIX.1 leaves these aspects of
 256 .BR signal ()
 257 unspecified.
 258 See
 259 .BR signal (2)
 260 for further details.
 261 .PP
 262 In order to wait for a signal,
 263 BSD and System V both provided a function named
 264 .BR sigpause (3),
 265 but this function has a different argument on the two systems.
 266 See
 267 .BR sigpause (3)
 268 for details.
 269 .SH SEE ALSO
 270 .BR kill (2),
 271 .BR pause (2),
 272 .BR sigaction (2),
 273 .BR signal (2),
 274 .BR sigprocmask (2),
 275 .BR raise (3),
 276 .BR sigpause (3),
 277 .BR sigset (3),
 278 .BR signal (7)