164 lines
4.0 KiB
Groff
164 lines
4.0 KiB
Groff
'\"macro stdmacro
|
|
.TH SIGWAIT 3
|
|
.SH NAME
|
|
sigwait, sigwaitinfo, sigtimedwait \- wait for queued signals (\s-1POSIX\s+1)
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.B #include <signal.h>
|
|
.B #include <sys/timers.h>
|
|
.PP
|
|
.B "int sigwait(const sigset_t *set, int *sig);
|
|
.B "int sigwaitinfo(const sigset_t *set, siginfo_t *value);
|
|
.B "int sigtimedwait(const sigset_t *set, siginfo_t *value, timespec_t *timeout);
|
|
.fi
|
|
.PP
|
|
.Op
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The
|
|
.I sigwait()
|
|
function selects a pending signal from
|
|
.I set
|
|
and returns it in the storage pointed to by
|
|
.I sig.
|
|
If multiple signals from
|
|
.I set
|
|
are pending, then the one with the lowest numerical value is selected.
|
|
If no signals in
|
|
.I set
|
|
are pending then the call will block until one becomes pending,
|
|
The signals defined by
|
|
.I set
|
|
must be blocked at the time of the call to
|
|
.I sigwait()
|
|
in order to avoid conflicts with installed signal handlers.
|
|
If the signals in
|
|
.I set
|
|
are not blocked then the system will either deliver the signal
|
|
asynchronously, or
|
|
.I sigwait()
|
|
will return with the signal. Users are advised to always block signals
|
|
in
|
|
.I set
|
|
to get predictable results.
|
|
.sp
|
|
The
|
|
.I sigwaitinfo()
|
|
call behaves the same as the
|
|
.I sigwait()
|
|
call if the
|
|
.I value
|
|
argument is NULL. If the
|
|
.I value
|
|
argument is non-NULL, the sigwaitinfo()
|
|
function behaves the same as
|
|
.I sigwait()
|
|
except the selected signal number is stored in the
|
|
.I si_signo
|
|
member, and the cause of the signal is stored in the
|
|
.I si_code
|
|
member. If any value was queued to the selected signal,
|
|
the first such queued value is dequeued and
|
|
the value is stored in the
|
|
.I si_value
|
|
member of
|
|
.I value.
|
|
The system resource used to queue the signal shall be released and made available to queue other signals. If no value is queued, the content of the
|
|
.I si_value
|
|
member is undefined. If no further signals are queued for the selected signal, the pending indication for that signal shall be reset.
|
|
.sp
|
|
The function
|
|
.I sigtimedwait()
|
|
behaves the same as
|
|
.I sigwaitinfo()
|
|
except that if none of the signals specified by
|
|
.I set
|
|
are pending,
|
|
.I sigtimedwait()
|
|
shall wait for the time interval specified in the
|
|
.I timespec
|
|
structure pointed to by
|
|
.I timeout.
|
|
If the
|
|
.I timespec
|
|
structure pointed to by
|
|
.I timeout
|
|
is zero-valued and if none of the signals specified by
|
|
.I set
|
|
are pending, then
|
|
.I sigtimedwait()
|
|
shall return immediately with an error. If
|
|
.I timeout
|
|
is the NULL pointer, the behavior is the same as
|
|
.I sigwaitinfo()
|
|
.sp
|
|
If any realtime signals (those in the range
|
|
.B SIGRTMIN
|
|
to
|
|
.BR SIGRTMAX )
|
|
are pending, the lowest numbered signal shall be returned.
|
|
The order in which realtime and nonrealtime signals are
|
|
returned is nondeterministic.
|
|
The order in which multiple nonrealtime signals are returned
|
|
is also nondeterministic.
|
|
.SH "SEE ALSO"
|
|
\f4kill\fP(2),
|
|
\f4sigaction\fP(2),
|
|
\f4sigqueue\fP(3),
|
|
\f4signal\fP(5),
|
|
\f4pthread_sigmask\fP(3P).
|
|
.SH "DIAGNOSTICS"
|
|
.PP
|
|
Upon successful completion,
|
|
.I sigwait()
|
|
returns a 0. Otherwise, it returns an error number to indicate the error.
|
|
.sp
|
|
Upon successful completion,
|
|
.I sigwaitinfo()
|
|
and
|
|
.I sigtimedwait()
|
|
return the selected signal number. Otherwise, they return a -1 and set
|
|
.I errno
|
|
to indicate the error number.
|
|
.sp
|
|
If any of the conditions below occur, the error number will take on the
|
|
corresponding value:
|
|
.TP 15
|
|
.SM
|
|
\%[EINTR]
|
|
The wait was interrupted by an unblocked, caught signal.
|
|
.P
|
|
If any of the following conditions occur, the
|
|
.I sigwait()
|
|
function shall return the corresponding value:
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
The
|
|
.I set
|
|
argument contains an invalid or unsupported signal number.
|
|
.P
|
|
If any of the following conditions occur, the
|
|
.I sigtimedwait()
|
|
function shall return -1 and set
|
|
.I errno
|
|
to the corresponding value:
|
|
.TP 15
|
|
.SM
|
|
\%[EAGAIN]
|
|
No signal specified by set was delivered within the specified timeout period.
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
The
|
|
.I timeout
|
|
argument specified a
|
|
.I tv_nsec
|
|
value less than zero or greater than or equal to 1 billion.
|
|
.SH "WARNING"
|
|
The \s-1POSIX\s+1 and System V signal facilities have different semantics.
|
|
Using both facilities in the same program is \f3strongly discouraged\fP
|
|
and will result in unpredictable behavior.
|
|
|