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