sigwait(2)                                                       sigwait(2)




 NAME    [Toc]    [Back]
      sigwait(), sigwaitinfo(), sigtimedwait() - synchronously accept a
      signal

 SYNOPSIS    [Toc]    [Back]
      #include <signal.h>

      int sigwait(const sigset_t *set, int *sig);

      int sigwaitinfo(const sigset_t *set, siginfo_t *info);

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

 DESCRIPTION    [Toc]    [Back]
      The sigwait() function atomically selects and clears a pending signal
      from set and returns the signal number in the location pointed to by
      sig.  If none of the signals in set is pending at the time of the
      call, the calling thread will be suspended until one or more signals
      become pending or the thread is interrupted by an unblocked, caught
      signal.  The signals in set should be blocked at the time of the call
      to sigwait().  Otherwise, the behavior is undefined.

      If there are multiple signals queued for the selected signal number,
      sigwait() will return with the first queued signal and the remainder
      will remain queued.  If any of multiple pending signals in the range
      SIGRTMIN to SIGRTMAX is selected, the lowest numbered signal will be
      returned.  The selection order between realtime and nonrealtime
      signals, or between multiple pending nonrealtime signals, is
      unspecified.

      If more than one thread in a process is in sigwait() for the same
      signal, only one thread will return from sigwait() with the signal
      number; which thread returns is undefined.

      sigwaitinfo() has the same behavior as sigwait() if the info parameter
      is NULL.  If the info parameter is not NULL, sigwaitinfo() has the
      same behavior as sigwait(), except that the selected signal number is
      returned in the si_signo field of the info parameter and the cause of
      the signal is returned in the si_code field.  If any value is queued
      to the selected signal, the first such queued value will be dequeued
      and stored in the si_value member of info and the system resource used
      to queue the signal will be released and made available to queue other
      signals. If no value is queued, the contents of the si_value member is
      undefined. If no further signals are queued for the selected signal,
      the pending indication for that signal will be reset.

      sigtimedwait() has the same behavior as sigwaitinfo() except that
      sigtimedwait() will only wait for the time interval specified by the
      timeout parameter if none of the signals specified by set are pending
      at the time of the call.  If the timeout parameter specifies a zero


 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 sigwait(2)                                                       sigwait(2)




      valued time interval, then sigtimedwait() will return immediately with
      an error if no signals in set are pending at the time of the call.  If
      the timeout parameter is NULL, the behavior is undefined.

 APPLICATION USAGE    [Toc]    [Back]
      For a given signal number, the sigwait family of routines should not
      be used in conjunction with sigaction() or any other functions which
      change signal action.  If they are used together, the results are
      undefined.

    Threads Considerations    [Toc]    [Back]
      The sigwait family of routines enable a thread to synchronously wait
      for signals.  This makes the sigwait routines ideal for handling
      signals in a multithreaded process.  The suggested method for signal
      handling in a multithreaded process is to have all threads block the
      signals of interest and dedicate one thread to call a sigwait function
      to wait for the signals.  When a signal causes a sigwait function to
      return, the code to handle the signal can be placed immediately after
      the return from the sigwait routine.  After the signal is handled, a
      sigwait function can again be called to wait for another signal.

      In order to ensure that the dedicated thread handles the signal, it is
      essential that all threads, including the thread issuing the sigwait
      call, block the signals of interest.  Otherwise, the signal could be
      delivered to a thread other than the dedicated signal handling thread.
      This could result in the default action being carried out for the
      signal.  It is important that the thread issuing the sigwait call also
      block the signal.  This will prevent signals from carrying out the
      default signal action while the dedicated signal handling thread is
      between calls to a sigwait function.

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, sigwait() stores the signal number
      selected in the location pointed to by sig and returns with a value of
      0 (zero).  Otherwise, it returns an error number to indicate the
      error.  The errno variable is NOT set if an error occurs.

      Upon successful completion, sigwaitinfo() and sigtimedwait() will
      return the selected signal number.  Otherwise a value of -1 is
      returned and errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If any of the following conditions occur, the sigwait family of
      routines will return the following error number:

           [EAGAIN]       sigtimedwait() was called and no signal in the set
                          parameter was delivered within the time interval
                          specified by the timeout parameter.

      If any of the following conditions occur and the condition is
      detected, the sigwait family of routines will fail and return the



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 sigwait(2)                                                       sigwait(2)




      following error number:

           [EINVAL]       set contains an invalid or unsupported signal
                          number.

           [EINVAL]       sigtimedwait() was called and the timeout
                          parameter specified a tv_nsec value less than zero
                          or greater than or equal to 1000 million, or a
                          tv_sec value less than zero or greater than or
                          equal to 2147483648 (that is, a value too large to
                          be represented as a signed 32-bit integer).

           [EINTR]        The wait was interrupted by an unblocked, caught
                          signal.

           [EFAULT]       At least one of the set, sig, info, or timeout
                          parameters references an illegal address.

 AUTHOR    [Toc]    [Back]
      sigwaitinfo() and sigtimedwait() were derived from the IEEE POSIX
      P1003.1b standard.

      sigwait() was derived from the IEEE POSIX P1003.1c standard.

 SEE ALSO    [Toc]    [Back]
      pause(2), sigaction(2), sigpending(2), sigsuspend(2),
      pthread_sigmask(3T), signal(5).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      sigwait(): POSIX.1c

      sigwaitinfo(): POSIX.1b

      sigtimedwait(): POSIX.1b


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003