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 is returned and
 176 .Va errno
 177 set to indicate the error.
 178 .Pp
 179 For all other functions, upon successful completion, 0 is returned.
 180 Otherwise, -1 is returned and
 181 .Va errno
 182 is set to indicate the error:
 183 .Bl -tag -width Er
 184 .It Bq Er EINVAL
 185 The
 186 .Fa sig
 187 argument
 188 is not a valid signal number.
 189 .It Bq Er EINVAL
 190 For
 191 .Fn sigset
 192 and
 193 .Fn sigignore
 194 functions, an attempt was made to catch or ignore
 195 .Dv SIGKILL
 196 or
 197 .Dv SIGSTOP .
 198 .Sh SEE ALSO
 199 .Xr kill 2 ,
 200 .Xr sigaction 2 ,
 201 .Xr sigblock 2 ,
 202 .Xr sigprocmask 2 ,
 203 .Xr sigsuspend 2 ,
 204 .Xr sigvec 2
 205 .Sh STANDARDS
 206 The
 207 .Fn sigpause
 208 function is implemented for compatibility with historic
 209 .Bx 4.3
 210 applications.
 211 An incompatible interface by the same name, which used a single signal number
 212 rather than a mask, was present in
 213 .At V ,
 214 and was copied from there into the
 215 .Sy X/Open System Interfaces
 216 .Pq Tn XSI
 217 option of
 218 .St -p1003.1-2001 .
 219 .Fx
 220 implements it under the name
 221 .Fn xsi_sigpause .
 222 The
 223 .Fn sighold ,
 224 .Fn sigignore ,
 225 .Fn sigrelse
 226 and
 227 .Fn sigset
 228 functions are implemented for compatibility with
 229 .Sy System V
 230 and
 231 .Sy XSI
 232 interfaces.
 233 .Sh HISTORY
 234 The
 235 .Fn sigpause
 236 function appeared in
 237 .Bx 4.2
 238 and has been deprecated.
 239 All other functions appeared in
 240 .Fx 8.1
 241 and were deprecated before being implemented.