Unix/Linux Go Back    


Linux 2.6 - man page for sigtimedwait (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


SIGTIMEDWAIT(P) 		    POSIX Programmer's Manual			  SIGTIMEDWAIT(P)

NAME
       sigtimedwait, sigwaitinfo - wait for queued signals (REALTIME)

SYNOPSIS
       #include <signal.h>

       int sigtimedwait(const sigset_t *restrict set,
	      siginfo_t *restrict info,
	      const struct timespec *restrict timeout);
       int sigwaitinfo(const sigset_t *restrict set,
	      siginfo_t *restrict info);

DESCRIPTION
       The  sigtimedwait()  function  shall be equivalent to sigwaitinfo() except that if none of
       the signals specified by set are pending, sigtimedwait() shall wait for the time  interval
       specified  in  the  timespec  structure	referenced  by timeout. If the timespec structure
       pointed to by timeout is zero-valued and if none of the signals specified by set are pend-
       ing,  then  sigtimedwait()  shall return immediately with an error. If 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 timeout
       argument.

       The sigwaitinfo() function selects the pending signal  from  the  set  specified  by  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
       set is pending at the time of the call, the calling thread shall be suspended until one or
       more signals in set become pending or until it is interrupted by an unblocked, caught sig-
       nal.

       The sigwaitinfo() function shall be equivalent to the sigwait() function if the info argu-
       ment is NULL. If the info argument is non-NULL, the sigwaitinfo() function shall be equiv-
       alent to sigwait(), except that the selected signal number shall be stored in the si_signo
       member, and the cause of the signal shall be stored in the si_code member. If any value is
       queued to the selected signal, the first such queued value shall be dequeued and,  if  the
       info  argument  is non-NULL, the value shall be stored in the si_value member of 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 si_value member is undefined. If no
       further signals are queued for the selected signal, the pending indication for that signal
       shall be reset.

RETURN VALUE
       Upon  successful completion (that is, one of the signals specified by set is pending or is
       generated) sigwaitinfo() and sigtimedwait() shall return the selected signal number.  Oth-
       erwise, the function shall return a value of -1 and set errno to indicate the error.

ERRORS
       The sigtimedwait() function shall fail if:

       EAGAIN No signal specified by set was generated within the specified timeout period.

       The sigtimedwait() and sigwaitinfo() functions may fail if:

       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.

       The sigtimedwait() function may also fail if:

       EINVAL The timeout argument specified a tv_nsec value less than zero or	greater  than  or
	      equal to 1000 million.

       An implementation only checks for this error if no signal is pending in set and it is nec-
       essary to wait.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       The sigtimedwait() function times out and returns an [EAGAIN] error.  Application  writers
       should  note  that  this  is inconsistent with other functions such as pthread_cond_timed-
       wait() that return [ETIMEDOUT].

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 sig-
       nal-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 individ-
       ual event handling.

       It is possible to construct a signal-waiting macro function out	of  the  realtime  signal
       function  mechanism  defined in this volume of IEEE Std 1003.1-2001. 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 IEEE Std 1003.1-2001	therefore
       provides  two signal-waiting functions-one that waits indefinitely and one with a timeout-
       as part of the overall realtime signal function specification.

       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.

       Note  that the semantics of the sigwaitinfo() function are nearly identical to that of the
       sigwait() function defined by this volume of IEEE Std 1003.1-2001. The only difference  is
       that  sigwaitinfo()  returns  the queued signal value in the value argument. The return of
       the queued value is required so	that  applications  can  differentiate	between  multiple
       events queued to the same signal number.

       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 sigwaitinfo() does not return the queued value if the value
       argument is NULL, so the POSIX Threads Extension sigwait() function can be implemented  as
       a macro on sigwaitinfo().

       The  sigtimedwait() function was separated from the sigwaitinfo() function to address con-
       cerns regarding the overloading of the 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 sigtimedwait() are specified such that sigwaitinfo()
       could be implemented as a macro with a NULL pointer for timeout.

       The sigwait functions provide a synchronous  mechanism  for  threads  to  wait  for  asyn-
       chronously-generated  signals.  One  important question was how many threads that are sus-
       pended in a call to a sigwait() function for a signal should return from the call when the
       signal is sent. Four choices were considered:

	1. Return an error for multiple simultaneous calls to sigwait functions for the same sig-
	   nal.

	2. One or more threads return.

	3. All waiting threads return.

	4. Exactly one thread returns.

       Prohibiting multiple calls to sigwait() for the same signal was felt to be overly restric-
       tive.  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
       sigwait()  in application code in order to achieve predictable behavior. There was concern
       that the "all waiting threads" behavior would result in "signal broadcast storms", consum-
       ing  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.

       Thus,  the consensus was that exactly one thread that was suspended in a call to a sigwait
       function for a signal should return when that  signal  occurs.  This  is  not  an  onerous
       restriction as:

	* A multi-way signal wait can be built from the single-way wait.

	* 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.

	* Applications can thus arrange for a single thread to wait for any given signal and call
	  any needed routines upon its arrival.

       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.

       Certainly, there exist programming styles where it is logical to consider  waiting  for	a
       single  signal in multiple threads. A simple sigwait_multiple() routine can be constructed
       to achieve this goal. A possible implementation would be to have  each  sigwait_multiple()
       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 sigwait() function
       on the union of all registered signals. When the sigwait() function returns, the appropri-
       ate state is set and condition variables are broadcast. New sigwait_multiple() callers may
       cause the pending sigwait() call to be canceled and reissued in order to update the set of
       signals being waited for.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Realtime Signals , pause() , pthread_sigmask() , sigaction() , sigpending() , sigsuspend()
       , sigwait() , the Base Definitions volume of IEEE Std 1003.1-2001, <signal.h>, <time.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				  SIGTIMEDWAIT(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 06:57 PM.