lib/libc/compat-43/sigpause.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)sigpause.2  8.1 (Berkeley) 6/2/93
  29 .\" $FreeBSD$
  30 .\"
  31 .\" Part of the content of the man page was derived from
  32 .\" The Open Group Base Specifications Issue 7
  33 .\" IEEE Std 1003.1-2008
  34 .\"
  35 .Dd June 2, 1993
  36 .Dt SIGPAUSE 2
  37 .Os
  38 .Sh NAME
  39 .Nm sighold ,
  40 .Nm sigignore ,
  41 .Nm sigpause ,
  42 .Nm sigrelse ,
  43 .Nm sigset
  44 .Nd legacy interface for signal management
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In signal.h
  49 .Ft int
  50 .Fn sighold "int sig"
  51 .Ft int
  52 .Fn sigignore "int sig"
  53 .Ft int
  54 .Fn xsi_sigpause "int sigmask"
  55 .Ft int
  56 .Fn sigrelse "int sig"
  57 .Ft void (*)(int)
  58 .Fn sigset "int" "void (*disp)(int)"
  59 .Ft int
  60 .Fn sigpause "int sigmask"
  61 .Sh DESCRIPTION
  62 .Sy This interface is made obsolete by
  63 .Xr sigsuspend 2
  64 .Sy and
  65 .Xr sigaction 2 .
  66 .Pp
  67 The
  68 .Fn sigset
  69 function modifies signal dispositions.
  70 The
  71 .Fa sig
  72 argument specifies the signal, which may be any signal except
  73 .Dv SIGKILL
  74 and
  75 .Dv SIGSTOP .
  76 The
  77 .Fa disp
  78 argument specifies the signal's disposition,
  79 which may be
  80 .Dv SIG_DFL ,
  81 .Dv SIG_IGN ,
  82 or the address of a signal handler.
  83 If
  84 .Fn sigset
  85 is used, and
  86 .Fa disp
  87 is the address of a signal handler, the
  88 system adds
  89 .Fa sig
  90 to the signal mask of the calling process before executing the signal
  91 handler; when the signal handler returns, the system restores the
  92 signal mask of the calling process to its state prior to the delivery
  93 of the signal.
  94 In addition, if
  95 .Fn sigset
  96 is used, and
  97 .Fa disp
  98 is equal to
  99 .Dv SIG_HOLD ,
 100 .Fa sig
 101 is added to the signal
 102 mask of the calling process and
 103 .Fa sig 's
 104 disposition remains unchanged.
 105 If
 106 .Fn sigset
 107 is used, and
 108 .Fa disp
 109 is not equal to
 110 .Dv SIG_HOLD ,
 111 .Fa sig
 112 is removed from the signal mask of the calling process.
 113 .Pp
 114 The
 115 .Fn sighold
 116 function adds
 117 .Fa sig
 118 to the signal mask of the calling process.
 119 .Pp
 120 The
 121 .Fn sigrelse
 122 function removes
 123 .Fa sig
 124 from the signal mask of the calling process.
 125 .Pp
 126 The
 127 .Fn sigignore
 128 function sets the disposition of
 129 .Fa sig
 130 to
 131 .Dv SIG_IGN .
 132 .Pp
 133 The
 134 .Fn xsi_sigpause
 135 function removes
 136 .Fa sig
 137 from the signal mask of the calling process and suspend the calling process
 138 until a signal is received.
 139 The
 140 .Fn xsi_sigpause
 141 function restores the signal mask of the process to its original state before
 142 returning.
 143 .Pp
 144 The
 145 .Fn sigpause
 146 function
 147 assigns
 148 .Fa sigmask
 149 to the set of masked signals
 150 and then waits for a signal to arrive;
 151 on return the set of masked signals is restored.
 152 The
 153 .Fa sigmask
 154 argument
 155 is usually 0 to indicate that no
 156 signals are to be blocked.
 157 .Sh RETURN VALUES
 158 The
 159 .Fn sigpause
 160 and
 161 .Fn xsi_sigpause
 162 functions
 163 always terminate by being interrupted, returning -1 with
 164 .Va errno
 165 set to
 166 .Er EINTR .
 167 .Pp
 168 Upon successful completion,
 169 .Fn sigset
 170 returns
 171 .Dv SIG_HOLD
 172 if the signal had been blocked and the signal's previous disposition if
 173 it had not been blocked.
 174 Otherwise,
 175 .Dv SIG_ERR
 176 is returned and
 177 .Va errno
 178 set to indicate the error.
 179 .Pp
 180 For all other functions, upon successful completion, 0 is returned.
 181 Otherwise, -1 is returned and
 182 .Va errno
 183 is set to indicate the error:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 The
 187 .Fa sig
 188 argument
 189 is not a valid signal number.
 190 .It Bq Er EINVAL
 191 For
 192 .Fn sigset
 193 and
 194 .Fn sigignore
 195 functions, an attempt was made to catch or ignore
 196 .Dv SIGKILL
 197 or
 198 .Dv SIGSTOP .
 199 .El
 200 .Sh SEE ALSO
 201 .Xr kill 2 ,
 202 .Xr sigaction 2 ,
 203 .Xr sigblock 2 ,
 204 .Xr sigprocmask 2 ,
 205 .Xr sigsuspend 2 ,
 206 .Xr sigvec 2
 207 .Sh STANDARDS
 208 The
 209 .Fn sigpause
 210 function is implemented for compatibility with historic
 211 .Bx 4.3
 212 applications.
 213 An incompatible interface by the same name, which used a single signal number
 214 rather than a mask, was present in
 215 .At V ,
 216 and was copied from there into the
 217 .Sy X/Open System Interfaces
 218 .Pq Tn XSI
 219 option of
 220 .St -p1003.1-2001 .
 221 .Fx
 222 implements it under the name
 223 .Fn xsi_sigpause .
 224 The
 225 .Fn sighold ,
 226 .Fn sigignore ,
 227 .Fn sigrelse
 228 and
 229 .Fn sigset
 230 functions are implemented for compatibility with
 231 .Sy System V
 232 and
 233 .Sy XSI
 234 interfaces.
 235 .Sh HISTORY
 236 The
 237 .Fn sigpause
 238 function appeared in
 239 .Bx 4.2
 240 and has been deprecated.
 241 All other functions appeared in
 242 .Fx 8.1
 243 and were deprecated before being implemented.