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 November 11, 2005
  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 If any value is queued to the selected signal, the first such queued
 120 value is dequeued and, if the info argument is
 121 .Pf non- Dv NULL ,
 122 the value is stored in the
 123 .Va si_value
 124 member of
 125 .Fa info .
 126 The system resource used to queue the signal
 127 is released and returned to the system for other use.
 128 If no value is queued,
 129 the content of the
 130 .Va si_value
 131 member is zero-valued.
 132 If no further signals are
 133 queued for the selected signal, the pending indication for that signal
 134 is reset.
 135 .Sh RETURN VALUES
 136 Upon successful completion (that is, one of the signals specified by
 137 .Fa set
 138 is pending or is generated)
 139 .Fn sigwaitinfo
 140 and
 141 .Fn sigtimedwait
 142 return the selected signal number.
 143 Otherwise, the functions return a value of \-1
 144 and set the global variable
 145 .Va errno
 146 to indicate the error.
 147 .Sh ERRORS
 148 The
 149 .Fn sigtimedwait
 150 system call
 151 will fail if:
 152 .Bl -tag -width Er
 153 .It Bq Er EAGAIN
 154 No signal specified by set was generated within the specified timeout period.
 155 .El
 156 .Pp
 157 The
 158 .Fn sigtimedwait
 159 and
 160 .Fn sigwaitinfo
 161 system calls fail if:
 162 .Bl -tag -width Er
 163 .It Bq Er EINTR
 164 The wait was interrupted by an unblocked, caught signal.
 165 .It Bq Er EFAULT
 166 Any arguments point outside the allocated address space or there is a
 167 memory protection fault.
 168 .Pp
 169 .El
 170 The
 171 .Fn sigtimedwait
 172 system call may also fail if:
 173 .Bl -tag -width Er
 174 .It Bq Er EINVAL
 175 The
 176 .Fa timeout
 177 argument specified a
 178 .Va tv_nsec
 179 value less than zero or greater than or equal
 180 to 1000 million.
 181 Kernel only checks for this error if no signal is pending in set and it
 182 is necessary to wait.
 183 .El
 184 .Sh SEE ALSO
 185 .Xr sigaction 2 ,
 186 .Xr sigpending 2 ,
 187 .Xr sigqueue 2 ,
 188 .Xr sigsuspend 2 ,
 189 .Xr sigwait 2 ,
 190 .Xr pause 3 ,
 191 .Xr pthread_sigmask 3 ,
 192 .Xr siginfo 3
 193 .Sh STANDARDS
 194 The
 195 .Fn sigtimedwait
 196 and
 197 .Fn sigwaitinfo
 198 system calls conform to
 199 .St -p1003.1-96 .