original/man3/sigset.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 SIGSET 3 2010-09-20 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 sigset, sighold, sigrelse, sigignore \- System V signal API
  27 .SH SYNOPSIS
  28 .B #include <signal.h>
  29 .sp
  30 .B typedef void (*sighandler_t)(int);
  31 .sp
  32 .BI "sighandler_t sigset(int " sig ", sighandler_t " disp );
  33 .sp
  34 .BI "int sighold(int " sig );
  35 .sp
  36 .BI "int sigrelse(int " sig );
  37 .sp
  38 .BI "int sigignore(int " sig );
  39 .sp
  40 .in -4n
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .in
  44 .sp
  45 .ad l
  46 .BR sigset (),
  47 .BR sighold (),
  48 .BR sigrelse (),
  49 .BR sigignore ():
  50 .br
  51 .RS 4
  52 _XOPEN_SOURCE\ >=\ 500 ||
  53 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  54 .RE
  55 .ad
  56 .SH DESCRIPTION
  57 These functions are provided in glibc as a compatibility interface
  58 for programs that make use of the historical System V signal API.
  59 This API is obsolete: new applications should use the POSIX signal API
  60 .RB ( sigaction (2),
  61 .BR sigprocmask (2),
  62 etc.)
  63
  64 The
  65 .BR sigset ()
  66 function modifies the disposition of the signal
  67 .IR sig .
  68 The
  69 .I disp
  70 argument can be the address of a signal handler function,
  71 or one of the following constants:
  72 .TP
  73 .B SIG_DFL
  74 Reset the disposition of
  75 .I sig
  76 to the default.
  77 .TP
  78 .B SIG_IGN
  79 Ignore
  80 .IR sig .
  81 .TP
  82 .B SIG_HOLD
  83 Add
  84 .I sig
  85 to the process's signal mask, but leave the disposition of
  86 .I sig
  87 unchanged.
  88 .PP
  89 If
  90 .I disp
  91 specifies the address of a signal handler, then
  92 .I sig
  93 is added to the process's signal mask during execution of the handler.
  94 .PP
  95 If
  96 .I disp
  97 was specified as a value other than
  98 .BR SIG_HOLD ,
  99 then
 100 .I sig
 101 is removed from the process's signal mask.
 102 .PP
 103 The dispositions for
 104 .B SIGKILL
 105 and
 106 .B SIGSTOP
 107 cannot be changed.
 108 .PP
 109 The
 110 .BR sighold ()
 111 function adds
 112 .I sig
 113 to the calling process's signal mask.
 114
 115 The
 116 .BR sigrelse ()
 117 function removes
 118 .I sig
 119 from the calling process's signal mask.
 120
 121 The
 122 .BR sigignore ()
 123 function sets the disposition of
 124 .I sig
 125 to
 126 .BR SIG_IGN .
 127 .SH RETURN VALUE
 128 On success,
 129 .BR sigset ()
 130 returns
 131 .B SIG_HOLD
 132 if
 133 .I sig
 134 was blocked before the call,
 135 or the signal's previous disposition
 136 if it was not blocked before the call.
 137 On error,
 138 .BR sigset ()
 139 returns \-1, with
 140 .I errno
 141 set to indicate the error.
 142 (But see BUGS below.)
 143
 144 The
 145 .BR sighold (),
 146 .BR sigrelse (),
 147 and
 148 .BR sigignore ()
 149 functions return 0 on success; on error, these functions return \-1 and set
 150 .I errno
 151 to indicate the error.
 152 .SH ERRORS
 153 For
 154 .BR sigset ()
 155 see the ERRORS under
 156 .BR sigaction (2)
 157 and
 158 .BR sigprocmask (2).
 159
 160 For
 161 .BR sighold ()
 162 and
 163 .BR sigrelse ()
 164 see the ERRORS under
 165 .BR sigprocmask (2).
 166
 167 For
 168 .BR sigignore (),
 169 see the errors under
 170 .BR sigaction (2).
 171 .SH "CONFORMING TO"
 172 SVr4, POSIX.1-2001.
 173 These functions are obsolete: do not use them in new programs.
 174 POSIX.1-2008 marks
 175 .BR sighold (),
 176 .BR sigignore (),
 177 .BR sigpause (),
 178 .BR sigrelse (),
 179 and
 180 .BR sigset ()
 181 as obsolete, recommending the use of
 182 .BR sigaction (2),
 183 .BR sigprocmask (2),
 184 .BR pthread_sigmask (3),
 185 and
 186 .BR sigsuspend (2)
 187 instead.
 188 .SH NOTES
 189 These functions appeared in glibc version 2.1.
 190
 191 The
 192 .I sighandler_t
 193 type is a GNU extension; it is only used on this page to make the
 194 .BR sigset ()
 195 prototype more easily readable.
 196
 197 The
 198 .BR sigset ()
 199 function provides reliable signal handling semantics (as when calling
 200 .BR sigaction (2)
 201 with
 202 .I sa_mask
 203 equal to 0).
 204
 205 On System V, the
 206 .BR signal ()
 207 function provides unreliable semantics (as when calling
 208 .BR sigaction (2)
 209 with
 210 .I sa_mask
 211 equal to
 212 .IR "SA_RESETHAND | SA_NODEFER" ).
 213 On BSD,
 214 .BR signal ()
 215 provides reliable semantics.
 216 POSIX.1-2001 leaves these aspects of
 217 .BR signal ()
 218 unspecified.
 219 See
 220 .BR signal (2)
 221 for further details.
 222
 223 In order to wait for a signal,
 224 BSD and System V both provided a function named
 225 .BR sigpause (3),
 226 but this function has a different argument on the two systems.
 227 See
 228 .BR sigpause (3)
 229 for details.
 230 .SH BUGS
 231 In versions of glibc before 2.2,
 232 .BR sigset ()
 233 did not unblock
 234 .I sig
 235 if
 236 .I disp
 237 was specified as a value other than
 238 .BR SIG_HOLD .
 239
 240 In versions of glibc before 2.5,
 241 .BR sigset ()
 242 does not correctly return the previous disposition of the signal
 243 in two cases.
 244 First, if
 245 .I disp
 246 is specified as
 247 .BR SIG_HOLD ,
 248 then a successful
 249 .BR sigset ()
 250 always returns
 251 .BR SIG_HOLD .
 252 Instead, it should return the previous disposition of the signal
 253 (unless the signal was blocked, in which case
 254 .B SIG_HOLD
 255 should be returned).
 256 Second, if the signal is currently blocked, then
 257 the return value of a successful
 258 .BR sigset ()
 259 should be
 260 .BR SIG_HOLD .
 261 Instead, the previous disposition of the signal is returned.
 262 These problems have been fixed since glibc 2.5.
 263 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951
 264 .SH "SEE ALSO"
 265 .BR kill (2),
 266 .BR pause (2),
 267 .BR sigaction (2),
 268 .BR signal (2),
 269 .BR sigprocmask (2),
 270 .BR raise (3),
 271 .BR sigpause (3),
 272 .BR sigvec (3),
 273 .BR signal (7)