usr/src/man/man3c/sigwaitinfo.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH SIGWAITINFO 3C "Feb 5, 2008"
  48 .SH NAME
  49 sigwaitinfo, sigtimedwait \- wait for queued signals
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <signal.h>
  54
  55 \fBint\fR \fBsigwaitinfo\fR(\fBconst sigset_t *restrict\fR \fIset\fR,
  56      \fBsiginfo_t *restrict\fR \fIinfo\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBint\fR \fBsigtimedwait\fR(\fBconst sigset_t *restrict\fR \fIset\fR,
  62      \fBsiginfo_t *restrict\fR \fIinfo\fR,
  63      \fBconst struct timespec *restrict\fR \fItimeout\fR);
  64 .fi
  65
  66 .SH DESCRIPTION
  67 .sp
  68 .LP
  69 The  \fBsigwaitinfo()\fR function selects the pending signal from the set
  70 specified by \fBset\fR. Should any of multiple pending signals in the range
  71 \fBSIGRTMIN\fR to \fBSIGRTMAX\fR be selected, it will be the lowest numbered
  72 one. The selection order between realtime and non-realtime signals, or between
  73 multiple pending non-realtime signals, is unspecified. If no signal in
  74 \fBset\fR is pending at the time of the call, the calling thread is suspended
  75 until one or more signals in \fBset\fR become pending or until it is
  76 interrupted by an unblocked, caught signal.
  77 .sp
  78 .LP
  79 The  \fBsigwaitinfo()\fR function behaves the same as the \fBsigwait\fR(2)
  80 function if the \fIinfo\fR argument is \fINULL\fR. If the \fIinfo\fR argument
  81 is non-\fINULL\fR, the \fBsigwaitinfo()\fR function behaves the same as
  82 \fBsigwait\fR(2), except that the selected signal number is stored in the
  83 \fIsi_signo\fR member, and the cause of the signal is stored in the
  84 \fIsi_code\fR member. If any value is queued to the selected signal, the first
  85 such queued value is dequeued and, if the \fIinfo\fR argument is
  86 non-\fINULL\fR, the value is stored in the \fIsi_value\fR member of \fIinfo\fR.
  87 The system resource used to queue the signal will be released and made
  88 available to queue other signals. If no value is queued, the content of the
  89 \fIsi_value\fR member is undefined. If no further signals are queued for the
  90 selected signal, the pending indication for that signal will be reset. If the
  91 value of the \fBsi_code\fR member is \fBSI_NOINFO\fR, only the \fBsi_signo\fR
  92 member of \fBsiginfo_t\fR is meaningful, and the value of all other members is
  93 unspecified.
  94 .sp
  95 .LP
  96 The  \fBsigtimedwait()\fR function behaves the same as \fBsigwaitinfo()\fR
  97 except that if none of the signals specified by \fBset\fR are pending,
  98 \fBsigtimedwait()\fR waits for the time interval specified in the
  99 \fBtimespec\fR structure referenced by \fItimeout\fR. If the \fBtimespec\fR
 100 structure pointed to by \fItimeout\fR is zero-valued and if none of the signals
 101 specified by \fBset\fR are pending, then \fBsigtimedwait()\fR returns
 102 immediately with an error. If \fItimeout\fR is the \fINULL\fR pointer, the
 103 behavior is unspecified.
 104 .sp
 105 .LP
 106 If, while \fBsigwaitinfo()\fR or \fBsigtimedwait()\fR is waiting, a signal
 107 occurs which is eligible for delivery (that is, not blocked by the process
 108 signal mask), that signal is handled asynchronously and the wait is
 109 interrupted.
 110 .SH RETURN VALUES
 111 .sp
 112 .LP
 113 Upon successful completion (that is, one of the signals specified by \fIset\fR
 114 is pending or is generated) \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR will
 115 return the selected signal number. Otherwise, the function returns \fB\(mi1\fR
 116 and sets \fBerrno\fR to indicate the error.
 117 .SH ERRORS
 118 .sp
 119 .LP
 120 The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions will fail if:
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEINTR\fR\fR
 125 .ad
 126 .RS 10n
 127 The wait was interrupted by an unblocked, caught signal.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBENOSYS\fR\fR
 134 .ad
 135 .RS 10n
 136 The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions are not supported.
 137 .RE
 138
 139 .sp
 140 .LP
 141 The \fBsigtimedwait()\fR function will fail if:
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBEAGAIN\fR\fR
 146 .ad
 147 .RS 10n
 148 No signal specified by \fBset\fR was generated within the specified timeout
 149 period.
 150 .RE
 151
 152 .sp
 153 .LP
 154 The \fBsigwaitinfo()\fR and \fBsigtimedwait()\fR functions may fail if:
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBEFAULT\fR\fR
 159 .ad
 160 .RS 10n
 161 The \fIset\fR, \fIinfo\fR, or \fItimeout\fR argument points to an invalid
 162 address.
 163 .RE
 164
 165 .sp
 166 .LP
 167 The \fBsigtimedwait()\fR function may fail if:
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBEINVAL\fR\fR
 172 .ad
 173 .RS 10n
 174 The \fItimeout\fR argument specified a \fBtv_nsec\fR value less than zero or
 175 greater than or equal to 1000 million. The system only checks for this error if
 176 no signal is pending in \fIset\fR and it is necessary to wait.
 177 .RE
 178
 179 .SH ATTRIBUTES
 180 .sp
 181 .LP
 182 See \fBattributes\fR(5) for descriptions of the following attributes:
 183 .sp
 184
 185 .sp
 186 .TS
 187 box;
 188 c | c
 189 l | l .
 190 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 191 _
 192 Interface Stability     Committed
 193 _
 194 MT-Level        Async-Safe
 195 _
 196 Standard        See \fBstandards\fR(5).
 197 .TE
 198
 199 .SH SEE ALSO
 200 .sp
 201 .LP
 202 \fBtime\fR(2), \fBsigqueue\fR(3C), \fBsiginfo.h\fR(3HEAD),
 203 \fBsignal.h\fR(3HEAD), \fBtime.h\fR(3HEAD), \fBattributes\fR(5),
 204 \fBstandards\fR(5)