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