diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/mageia-cauldron/man3p/sigtimedwait.3p | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/sigtimedwait.3p b/upstream/mageia-cauldron/man3p/sigtimedwait.3p new file mode 100644 index 00000000..361ad755 --- /dev/null +++ b/upstream/mageia-cauldron/man3p/sigtimedwait.3p @@ -0,0 +1,363 @@ +'\" et +.TH SIGTIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigtimedwait, +sigwaitinfo +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include <signal.h> +.P +int sigtimedwait(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP, + const struct timespec *restrict \fItimeout\fP); +int sigwaitinfo(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP); +.fi +.SH DESCRIPTION +The +\fIsigtimedwait\fR() +function shall be equivalent to +\fIsigwaitinfo\fR() +except that if none of the signals specified by +.IR set +are pending, +\fIsigtimedwait\fR() +shall wait for the time interval specified in the +.BR timespec +structure referenced by +.IR timeout . +If the +.BR timespec +structure pointed to by +.IR timeout +is zero-valued and if none of the signals specified by +.IR set +are pending, then +\fIsigtimedwait\fR() +shall return immediately with an error. If +.IR timeout +is the null pointer, the behavior is unspecified. +If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock +shall be used to measure the time interval specified by the +.IR timeout +argument. +.P +The +\fIsigwaitinfo\fR() +function selects the pending signal from the set specified by +.IR set . +Should any of multiple pending signals in the range SIGRTMIN to +SIGRTMAX be selected, +it shall be the lowest numbered one. The selection order between +realtime and non-realtime signals, or between multiple pending +non-realtime signals, is unspecified. If no signal in +.IR set +is pending at the time of the call, the calling thread shall be +suspended until one or more signals in +.IR set +become pending or until it is interrupted by an unblocked, caught +signal. +.P +The +\fIsigwaitinfo\fR() +function shall be equivalent to the +\fIsigwait\fR() +function, except that the return value and the error reporting method +are different (see RETURN VALUE), and that if the +.IR info +argument is non-NULL, the selected signal number shall be stored in the +.IR si_signo +member, and the cause of the signal shall be stored in the +.IR si_code +member. If any value is queued to the selected signal, the first such +queued value shall be dequeued and, if the +.IR info +argument is non-NULL, the value shall be stored in the +.IR si_value +member of +.IR info . +The system resource used to queue the signal shall be released and +returned to the system for other use. If no value is queued, the +content of the +.IR si_value +member is undefined. If no further signals are queued for the selected +signal, the pending indication for that signal shall be reset. +.SH "RETURN VALUE" +Upon successful completion (that is, one of the signals specified by +.IR set +is pending or is generated) +\fIsigwaitinfo\fR() +and +\fIsigtimedwait\fR() +shall return the selected signal number. Otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigtimedwait\fR() +function shall fail if: +.TP +.BR EAGAIN +No signal specified by +.IR set +was generated within the specified timeout period. +.P +The +\fIsigtimedwait\fR() +and +\fIsigwaitinfo\fR() +functions may fail if: +.TP +.BR EINTR +The wait was interrupted by an unblocked, caught signal. It shall be +documented in system documentation whether this error causes these +functions to fail. +.br +.P +The +\fIsigtimedwait\fR() +function may also fail if: +.TP +.BR EINVAL +The +.IR timeout +argument specified a +.IR tv_nsec +value less than zero or greater than or equal to 1\|000 million. +.P +An implementation should only check for this error if no signal is +pending in +.IR set +and it is necessary to wait. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigtimedwait\fR() +function times out and returns an +.BR [EAGAIN] +error. Application developers should note that this is inconsistent +with other functions such as +\fIpthread_cond_timedwait\fR() +that return +.BR [ETIMEDOUT] . +.P +Note that in order to ensure that generated signals are queued and signal +values passed to +\fIsigqueue\fR() +are available in +.IR si_value , +applications which use +\fIsigwaitinfo\fR() +or +\fIsigtimedwait\fR() +need to set the SA_SIGINFO flag for each signal in the set (see +.IR "Section 2.4" ", " "Signal Concepts"). +This means setting each signal to be handled by a three-argument +signal-catching function, even if the handler will never be called. +It is not possible (portably) to set a signal handler to SIG_DFL while +setting the SA_SIGINFO flag, because assigning to the +.IR sa_handler +member of +.BR "struct sigaction" +instead of the +.IR sa_sigaction +member would result in undefined behavior, and SIG_DFL need not be +assignment-compatible with +.IR sa_sigaction . +Even if an assignment of SIG_DFL to +.IR sa_sigaction +is accepted by the compiler, the implementation need not treat this value +as special\(emit could just be taken as the address of a signal-catching +function. +.SH RATIONALE +Existing programming practice on realtime systems uses the ability to +pause waiting for a selected set of events and handle the first event +that occurs in-line instead of in a signal-handling function. This +allows applications to be written in an event-directed style similar to +a state machine. This style of programming is useful for largescale +transaction processing in which the overall throughput of an +application and the ability to clearly track states are more important +than the ability to minimize the response time of individual event +handling. +.P +It is possible to construct a signal-waiting macro function out of the +realtime signal function mechanism defined in this volume of POSIX.1\(hy2017. However, such a +macro has to include the definition of a generalized handler for all +signals to be waited on. A significant portion of the overhead of +handler processing can be avoided if the signal-waiting function is +provided by the kernel. This volume of POSIX.1\(hy2017 therefore provides two signal-waiting +functions\(emone that waits indefinitely and one with a timeout\(emas +part of the overall realtime signal function specification. +.P +The specification of a function with a timeout allows an application +to be written that can be broken out of a wait after a set period of +time if no event has occurred. It was argued that setting a timer +event before the wait and recognizing the timer event in the wait would +also implement the same functionality, but at a lower performance +level. Because of the performance degradation associated with the +user-level specification of a timer event and the subsequent +cancellation of that timer event after the wait completes for a valid +event, and the complexity associated with handling potential race +conditions associated with the user-level method, the separate +function has been included. +.P +Note that the semantics of the +\fIsigwaitinfo\fR() +function are nearly identical to that of the +\fIsigwait\fR() +function defined by this volume of POSIX.1\(hy2017. The only difference is that +\fIsigwaitinfo\fR() +returns the queued signal value in the +.IR value +argument. The return of the queued value is required so that +applications can differentiate between multiple events queued to the +same signal number. +.P +The two distinct functions are being maintained because some +implementations may choose to implement the POSIX Threads Extension functions and not +implement the queued signals extensions. Note, though, that +\fIsigwaitinfo\fR() +does not return the queued value if the +.IR value +argument is NULL, so the POSIX Threads Extension +\fIsigwait\fR() +function can be implemented as a macro on +\fIsigwaitinfo\fR(). +.P +The +\fIsigtimedwait\fR() +function was separated from the +\fIsigwaitinfo\fR() +function to address concerns regarding the overloading of the +.IR timeout +pointer to indicate indefinite wait (no timeout), timed wait, and +immediate return, and concerns regarding consistency with other +functions where the conditional and timed waits were separate +functions from the pure blocking function. The semantics of +\fIsigtimedwait\fR() +are specified such that +\fIsigwaitinfo\fR() +could be implemented as a macro with a null pointer for +.IR timeout . +.P +The +.IR sigwait +functions provide a synchronous mechanism for threads to wait for +asynchronously-generated signals. One important question was how many +threads that are suspended in a call to a +\fIsigwait\fR() +function for a signal should return from the call when the signal is +sent. Four choices were considered: +.IP " 1." 4 +Return an error for multiple simultaneous calls to +.IR sigwait +functions for the same signal. +.IP " 2." 4 +One or more threads return. +.IP " 3." 4 +All waiting threads return. +.IP " 4." 4 +Exactly one thread returns. +.P +Prohibiting multiple calls to +\fIsigwait\fR() +for the same signal was felt to be overly restrictive. The ``one or +more'' behavior made implementation of conforming packages easy at the +expense of forcing POSIX threads clients to protect against multiple +simultaneous calls to +\fIsigwait\fR() +in application code in order to achieve predictable behavior. There +was concern that the ``all waiting threads'' behavior would result in +``signal broadcast storms'', consuming excessive CPU resources by +replicating the signals in the general case. Furthermore, no +convincing examples could be presented that delivery to all was either +simpler or more powerful than delivery to one. +.P +Thus, the consensus was that exactly one thread that was suspended in a +call to a +.IR sigwait +function for a signal should return when that signal occurs. This is +not an onerous restriction as: +.IP " *" 4 +A multi-way signal wait can be built from the single-way wait. +.IP " *" 4 +Signals should only be handled by application-level code, as library +routines cannot guess what the application wants to do with signals +generated for the entire process. +.IP " *" 4 +Applications can thus arrange for a single thread to wait for any given +signal and call any needed routines upon its arrival. +.P +In an application that is using signals for interprocess communication, +signal processing is typically done in one place. Alternatively, if +the signal is being caught so that process cleanup can be done, the +signal handler thread can call separate process cleanup routines for +each portion of the application. Since the application main line +started each portion of the application, it is at the right abstraction +level to tell each portion of the application to clean up. +.P +Certainly, there exist programming styles where it is logical to +consider waiting for a single signal in multiple threads. A simple +\fIsigwait_multiple\fR() +routine can be constructed to achieve this goal. A possible +implementation would be to have each +\fIsigwait_multiple\fR() +caller registered as having expressed interest in a set of signals. +The caller then waits on a thread-specific condition variable. A +single server thread calls a +\fIsigwait\fR() +function on the union of all registered signals. When the +\fIsigwait\fR() +function returns, the appropriate state is set and condition variables +are broadcast. New +\fIsigwait_multiple\fR() +callers may cause the pending +\fIsigwait\fR() +call to be canceled and reissued in order to update the set of signals +being waited for. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "Section 2.8.1" ", " "Realtime Signals", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<signal.h>\fP", +.IR "\fB<time.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |