man3/sigvec.3

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