sigwait(2)                                                sigwait(2)


       NAME
             sigwait - wait for a signal to be posted

       SYNOPSIS
             #include <signal.h>

             int sigwait(sigset_t *set);

       DESCRIPTION
             This function atomically chooses and clears a pending signal
             from set and returns the number of the signal chosen.  If no
             signal in set is pending at the time of the call, the calling
             function shall be suspended until one or more signals become
             pending.  This suspension is indefinite in extent.

             The set of signals remains blocked after return.

             An application should not mix use of sigwait and sigaction for
             a given signal number because the results may be
             unpredictable.

          Return Values
             Upon successful completion, sigwait returns the signal number
             of the received signal.  Otherwise, a negative value is
             returned and errno is set to indicate the error.

          Errors
             If any of the following conditions occurs, sigwait returns a
             negative value and sets errno to the corresponding value:

             EINVAL   set contains an invalid or unsupported signal number

             EFAULT   set points to an illegal address.

       REFERENCES
             _lwp_kill(2), kill(2), sigaction(2), signal(5), sigpending(2),
             sigsend(2), sigsuspend(2), thread(3thread)

       NOTICES
          Considerations for Threads Programming
             The sigwait system call allows a multithreaded application to
             use a synchronous organization for signal handling.

          Usage
             The semantics of sigwait make it ideal for a thread that will
             be dedicated to handling certain signal types for a process.


                           Copyright 1994 Novell, Inc.               Page 1

      sigwait(2)                                                sigwait(2)


            The functionality that might have been placed in a separate
            handler function could be placed after the return from sigwait
            to be executed once a signal arrives. Once handling is
            complete, the thread could call sigwait again to block itself
            until arrival of the next signal.

            To be sure that signals are delivered to the intended thread:

                  All threads in the process (including the thread that
                  will be using sigwait) should mask the relevant signal
                  types.

                  Only the intended thread should use sigwait.

                  No thread should define a handler function.

            See signal(5) for further details.

            Code to handle a signal type on return from sigwait is not
            considered a handler in the containing process' disposition
            for that signal type.  It is important that signal types
            handled by a thread using sigwait(2) be included in the signal
            mask of every thread, otherwise, the default response for the
            process will be triggered.  Even the thread calling sigwait
            should mask that signal type because a signal of that type may
            arrive while the thread is between calls to sigwait(2).

            While one thread is blocked, siblings might still be
            executing.



















                          Copyright 1994 Novell, Inc.               Page 2