original/man3/sigvec.3

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