lib/libc/sys/sigwaitinfo.2

   1 .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
   2 .\" 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(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd September 27, 2012
  31 .Dt SIGTIMEDWAIT 2
  32 .Os
  33 .Sh NAME
  34 .Nm sigtimedwait , sigwaitinfo
  35 .Nd "wait for queued signals (REALTIME)"
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In signal.h
  40 .Ft int
  41 .Fo sigtimedwait
  42 .Fa "const sigset_t *restrict set" "siginfo_t *restrict info"
  43 .Fa "const struct timespec *restrict timeout"
  44 .Fc
  45 .Ft int
  46 .Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn sigtimedwait
  50 system call is equivalent to
  51 .Fn sigwaitinfo
  52 except that if none of the signals specified by
  53 .Fa set
  54 are pending,
  55 .Fn sigtimedwait
  56 waits for the time interval specified in the
  57 .Vt timespec
  58 structure referenced by
  59 .Fa timeout .
  60 If the
  61 .Vt timespec
  62 structure pointed to by
  63 .Fa timeout
  64 is zero-valued and if none of the signals specified by
  65 .Fa set
  66 are pending, then
  67 .Fn sigtimedwait
  68 returns immediately with an error.
  69 If
  70 .Fa timeout
  71 is the
  72 .Dv NULL
  73 pointer, the behavior is unspecified.
  74 .Dv CLOCK_MONOTONIC
  75 clock is used to measure the time interval specified by the
  76 .Fa timeout
  77 argument.
  78 .Pp
  79 The
  80 .Fn sigwaitinfo
  81 system call selects the pending signal from the set specified by
  82 .Fa set .
  83 Should any of multiple pending signals in the range
  84 .Dv SIGRTMIN
  85 to
  86 .Dv SIGRTMAX
  87 be selected, it shall be the lowest numbered one.
  88 The
  89 selection order between realtime and non-realtime signals, or
  90 between multiple pending non-realtime signals, is unspecified.
  91 If no signal in
  92 .Fa set
  93 is pending at the time of the call, the calling thread
  94 is suspended until one or more signals in
  95 .Fa set
  96 become pending or until it is interrupted by an unblocked, caught signal.
  97 .Pp
  98 The
  99 .Fn sigwaitinfo
 100 system call is equivalent to the
 101 .Fn sigwait
 102 system call if the
 103 .Fa info
 104 argument is
 105 .Dv NULL .
 106 If the
 107 .Fa info
 108 argument is
 109 .Pf non- Dv NULL ,
 110 the
 111 .Fn sigwaitinfo
 112 function is equivalent to
 113 .Fn sigwait ,
 114 except that the selected signal number shall be stored in the
 115 .Va si_signo
 116 member, and the cause of the signal shall be stored in the
 117 .Va si_code
 118 member.
 119 Besides this, the
 120 .Fn sigwaitinfo
 121 and
 122 .Fn sigtimedwait
 123 system calls may return
 124 .Er EINTR
 125 if interrupted by signal, which is not allowed for the
 126 .Fn sigwait
 127 function.
 128 .Pp
 129 If any value is queued to the selected signal, the first such queued
 130 value is dequeued and, if the info argument is
 131 .Pf non- Dv NULL ,
 132 the value is stored in the
 133 .Va si_value
 134 member of
 135 .Fa info .
 136 The system resource used to queue the signal
 137 is released and returned to the system for other use.
 138 If no value is queued,
 139 the content of the
 140 .Va si_value
 141 member is zero-valued.
 142 If no further signals are
 143 queued for the selected signal, the pending indication for that signal
 144 is reset.
 145 .Sh RETURN VALUES
 146 Upon successful completion (that is, one of the signals specified by
 147 .Fa set
 148 is pending or is generated)
 149 .Fn sigwaitinfo
 150 and
 151 .Fn sigtimedwait
 152 return the selected signal number.
 153 Otherwise, the functions return a value of \-1
 154 and set the global variable
 155 .Va errno
 156 to indicate the error.
 157 .Sh ERRORS
 158 The
 159 .Fn sigtimedwait
 160 system call
 161 will fail if:
 162 .Bl -tag -width Er
 163 .It Bq Er EAGAIN
 164 No signal specified by set was generated within the specified timeout period.
 165 .El
 166 .Pp
 167 The
 168 .Fn sigtimedwait
 169 and
 170 .Fn sigwaitinfo
 171 system calls fail if:
 172 .Bl -tag -width Er
 173 .It Bq Er EINTR
 174 The wait was interrupted by an unblocked, caught signal.
 175 .Pp
 176 .El
 177 The
 178 .Fn sigtimedwait
 179 system call may also fail if:
 180 .Bl -tag -width Er
 181 .It Bq Er EINVAL
 182 The
 183 .Fa timeout
 184 argument specified a
 185 .Va tv_nsec
 186 value less than zero or greater than or equal
 187 to 1000 million.
 188 Kernel only checks for this error if no signal is pending in set and it
 189 is necessary to wait.
 190 .El
 191 .Sh SEE ALSO
 192 .Xr sigaction 2 ,
 193 .Xr sigpending 2 ,
 194 .Xr sigqueue 2 ,
 195 .Xr sigsuspend 2 ,
 196 .Xr sigwait 2 ,
 197 .Xr pause 3 ,
 198 .Xr pthread_sigmask 3 ,
 199 .Xr siginfo 3
 200 .Sh STANDARDS
 201 The
 202 .Fn sigtimedwait
 203 and
 204 .Fn sigwaitinfo
 205 system calls conform to
 206 .St -p1003.1-96 .