.\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
-.TH SIGWAITINFO 2 2008-10-04 "Linux" "Linux Programmer's Manual"
+.TH SIGWAITINFO 2 2014-08-19 "Linux" "Linux Programmer's Manual"
.SH NAME
sigwaitinfo, sigtimedwait \- synchronously wait for queued signals
.SH SYNOPSIS
.BR sigwaitinfo ()
suspends execution of the calling thread until one of the signals in
.I set
-is delivered.
+is pending
(If one of the signals in
.I set
is already pending for the calling thread,
.BR sigwaitinfo ()
-will return immediately with information about that signal.)
+will return immediately.)
.BR sigwaitinfo ()
-removes the delivered signal from the set of pending
+removes the signal from the set of pending
signals and returns the signal number as its function result.
If the
.I info
argument is not NULL,
-then it returns a structure of type
+then the buffer that it points to is used to return a structure of type
.I siginfo_t
(see
.BR sigaction (2))
containing information about the signal.
.PP
-Signals returned via
+If multiple signals in
+.I set
+are pending for the caller, the signal that is retrieved by
.BR sigwaitinfo ()
-are delivered in the usual order; see
+is determined according to the usual ordering rules; see
.BR signal (7)
for further details.
.PP
.BR sigwaitinfo ()
except that it has an additional argument,
.IR timeout ,
-which enables an upper bound to be placed on the time for which
-the thread is suspended.
+which specifies the interval for which
+the thread is suspended waiting for a signal.
+(This interval will be rounded up to the system clock granularity,
+and kernel scheduling delays mean that the interval
+may overrun by a small amount.)
This argument is of the following type:
.sp
.in +4n
if none of the signals in
.I set
was pending.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success, both
.BR sigwaitinfo ()
and
.B EAGAIN
No signal in
.I set
-was delivered within the
+was became pending within the
.I timeout
period specified to
.BR sigtimedwait ().
.B EINVAL
.I timeout
was invalid.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
POSIX.1-2001.
.SH NOTES
In normal usage, the calling program blocks the signals in
via a prior call to
.BR sigprocmask (2)
(so that the default disposition for these signals does not occur if they
-are delivered between successive calls to
+become pending between successive calls to
.BR sigwaitinfo ()
or
.BR sigtimedwait ())
and does not establish handlers for these signals.
In a multithreaded program,
-the signal should be blocked in all threads to prevent
-the signal being delivered to a thread other than the one calling
+the signal should be blocked in all threads, in order to prevent
+the signal being treated according to its default disposition in
+a thread other than the one calling
.BR sigwaitinfo ()
or
.BR sigtimedwait ()).
and the set of signals that is pending for the process as a whole (see
.BR signal (7)).
+Attempts to wait for
+.B SIGKILL
+and
+.B SIGSTOP
+are silently ignored.
+
If multiple threads of a process are blocked
waiting for the same signal(s) in
.BR sigwaitinfo ()
or
.BR sigtimedwait (),
then exactly one of the threads will actually receive the
-signal if it is delivered to the process as a whole;
+signal if it becomes pending for the process as a whole;
which of the threads receives the signal is indeterminate.
POSIX leaves the meaning of a NULL value for the
as a call to
.BR sigwaitinfo (),
and indeed this is what is done on Linux.
-
+.\"
+.SS C library/kernel ABI differences
On Linux,
.BR sigwaitinfo ()
is a library function implemented on top of
.BR sigtimedwait ().
-.SH "SEE ALSO"
+
+The raw
+.BR sigtimedwait ()
+system call has a fifth argument,
+.IR "size_t sigsetsize" ,
+which specifies the size in bytes of the
+.IR set
+argument.
+The glibc
+.BR sigtimedwait ()
+wrapper function specifies this argument as a fixed value
+(equal to
+.IR sizeof(sigset_t) ).
+.SH SEE ALSO
.BR kill (2),
.BR sigaction (2),
.BR signal (2),
.BR signalfd (2),
.BR sigpending (2),
.BR sigprocmask (2),
-.BR sigqueue (2),
+.BR sigqueue (3),
.BR sigsetops (3),
.BR sigwait (3),
.BR signal (7),
.BR time (7)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.