\function{alarm}
\synopsis{Schedule an alarm signal}
\usage{alarm (UInt_Type secs [, Ref_Type secs_remaining])}
\description
  The \ifun{alarm} function schedules the delivery of a \icon{SIGALRM}
  signal in \exmp{secs} seconds.  Any previously scheduled alarm will
  be canceled.  If \exmp{secs} is zero, then no new alarm will be
  scheduled.  If the second argument is present, then it must be a
  reference to a variable whose value will be set upon return to the
  number of seconds remaining for a previously scheduled alarm to take
  place.
\example
  This example demonstrates how the \ifun{alarm} function may be
  used to read from \ivar{stdin} within a specified amount of time:
#v+
    define sigalrm_handler (sig)
    {
       throw ReadError, "Read timed out";
    }
    define read_or_timeout (secs)
    {
       variable line, err;
       signal (SIGALRM, &sigalrm_handler);
       () = fputs ("Enter some text> ", stdout); () = fflush (stdout);
       alarm (secs);
       try (err)
         {
            if (-1 == fgets (&line, stdin))
              throw ReadError, "Failed to read from stdin";
         }
       catch IOError:
         {
            message (err.message);
            return NULL;
         }
       return line;
    }
#v-
\notes
  Some operating systems may implement the \ifun{sleep} function using
  \ifun{alarm}.  As a result, it is not a good idea to mix calls to
  \ifun{alarm} and \ifun{sleep}.

  The default action for \icon{SIGALRM} is to terminate the process.
  Hence, if \ifun{alarm} is called it is wise to establish a signal
  handler for \ifun{SIGALRM}.
\seealso{signal, sleep, setitimer, getitimer}
\done

\function{getitimer}
\synopsis{Get the value of an interval timer}
\usage{(secs, period) = getitimer (Int_Type timer)}
\description
  This function returns the value of the specified interval timer as a
  pair of double precision values: \exmp{period} and \exmp{secs}.

  The value of \exmp{secs} indicates the number of seconds
  remaining before the timer expires.  A value of 0 for
  \exmp{secs} indicates that the timer is inactive.
  The value of \exmp{period} indicates the periodicity of the timer.
  That is, when the timer goes off, it will automatically be reset to
  go off again after \exmp{period} seconds.

  There are 3 interval timers available: \icon{ITIMER_REAL},
  \icon{ITIMER_VIRTUAL}, and \icon{ITIMER_PROF}.

  The \icon{ITIMER_REAL} timer operates in real time and when the time
  elapses, a \icon{SIGALRM} will be sent to the process.

  The \icon{ITIMER_VIRTUAL} timer operates in the virtual time of the
  process; that is, when process is actively running.  When it
  elapses, \icon{SIGVTALRM} will be sent to the process.

  The \icon{ITIMER_PROF} operates when the process is actively
  running, or when the kernel is performing a task on behalf of the
  process.  It sends a \icon{SIGPROF} signal to the process.
\notes
  The interaction between these timers and the \ifun{sleep} and
  \ifun{alarm} functions is OS dependent.

  The resolution of a timer is system dependent; typical values are on
  the order of milliseconds.
\seealso{setitimer, alarm, signal}
\done

\function{setitimer}
\synopsis{Set the value of an interval timer}
\usage{setitimer (Int_Type timer, secs [, period] [,&old_secs, &old_period])}
\description
  This function sets the value of a specified interval timer, and
  optionally returns the previous value.  The value of the
  \exmp{timer} argument must be one of the 3 interval timers
  \icon{ITIMER_REAL}, \icon{ITIMER_VIRTUAL}, or \icon{ITIMER_PROF}.
  See the documentation for the \ifun{getitimer} function for
  information about the semantics of these timers.

  The value of the \exmp{secs} parameter specifies the expiration time
  for the timer.  If this value is 0, the timer will be disabled.
  Unless a non-zero value for the optional \exmp{period} parameter is
  given, the timer will be disabled after it expires.  Otherwise,
  the timer will reset to go off with a period of \exmp{period} seconds.

  The final two optional arguments are references to variables that
  will be set to the previous values associated with the timer.
\seealso{getitimer, alarm, signal}
\done

\function{signal}
\synopsis{Establish a signal handler}
\usage{signal (Int_Type sig, Ref_Type func [,Ref_Type old_func])}
\description
  The \ifun{signal} function assigns the signal handler represented by
  \exmp{func} to the signal \exmp{sig}.  Here \exmp{func} is usually
  reference to a function that takes an integer argument (the signal)
  and returns nothing, e.g.,
#v+
    define signal_handler (sig)
    {
       return;
    }
#v-
  Alternatively, \exmp{func} may be given by one of the symbolic
  constants \icon{SIG_IGN} or \icon{SIG_DFL} to indicate that the
  signal is to be ignored or given its default action, respectively.

  The first parameter, \exmp{sig}, specifies the signal to be handled.
  The actual supported values vary with the OS.  Common values on Unix
  include \exmp{SIGHUP}, \exmp{SIGINT}, and \exmp{SIGTERM}.

  If a third argument is present, then it must be a reference to a
  variable whose value will be set to the value of the previously
  installed handler.
\example
  This example establishes a handler for \exmp{SIGTSTP}.
#v+
    static define sig_suspend ();  % forward declaration
    static define sig_suspend (sig)
    {
       message ("SIGTSTP received-- stopping");
       signal (sig, SIG_DFL);
       () = kill (getpid(), SIGSTOP);
       message ("Resuming");
       signal (sig, &sig_suspend);
    }
    signal (SIGTSTP, &sig_suspend);
#v-
\notes
  Currently the signal interface is supported only on systems that
  implement signals according to the POSIX standard.

  Once a signal has been received, it will remain blocked until after
  the signal handler has completed.  This is the reason \icon{SIGSTOP}
  was used in the above signal handler instead of \icon{SIGTSTP}.
\seealso{alarm, sigsuspend, sigprocmask}
\done

\function{sigprocmask}
\synopsis{Change the list of currently blocked signals}
\usage{sigprocmask (Int_Type how, Array_Type mask [,Ref_Type old_mask])}
\description
  The \ifun{sigprocmask} function may be used to change the list of
  signals that are currently blocked.  The first parameter indicates
  how this is accomplished.  Specifically, \exmp{how} must be one of
  the following values: \icon{SIG_BLOCK}, \icon{SIG_UNBLOCK}, or
  \icon{SIG_SETMASK}.

  If \exmp{how} is \icon{SIG_BLOCK}, then the set of blocked signals
  will be the union the current set with the values specified in the
  \exmp{mask} argument.

  If \exmp{how} is \icon{SIG_UNBLOCK}, then the signals specified by
  the \exmp{mask} parameter will be removed from the currently blocked
  set.

  If \exmp{how} is \icon{SIG_SETMASK}, then the set of blocked signals
  will be set to those given by the \exmp{mask}.

  If a third argument is present, then it must be a reference to a
  variable whose value will be set to the previous signal mask.
\seealso{signal, sigsuspend, alarm}
\done

\function{sigsuspend}
\synopsis{Suspend the process until a signal is delivered}
\usage{sigsuspend ([Array_Type signal_mask])}
\description
  The \ifun{sigsuspend} function suspends the current process
  until a signal is received.  An optional array argument may be
  passed to the function to specify a list of signals that should be
  temporarily blocked while waiting for a signal.
\example
  The following example pauses the current process for 10 seconds
  while blocking the \icon{SIGHUP} and \icon{SIGINT} signals.
#v+
     static variable Tripped;
     define sigalrm_handler (sig)
     {
        Tripped = 1;
     }
     signal (SIGALRM, &sigalrm_handler);
     Tripped = 0;
     alarm (10);
     while (Tripped == 0) sigsuspend ([SIGHUP, SIGINT]);
#v-
  Note that in this example the call to \ifun{sigsuspend} was wrapped in
  a while-loop.  This was necessary because there is no guarantee that
  another signal would not cause \ifun{sigsuspend} to return.
\seealso{signal, alarm, sigprocmask}
\done