doc sleep and itimers

[Kevin Ryde]

I had a bit of a go at polishing the docs on sleep, usleep, getitimer
and setitimer.  The bit that said usleep wasn't available on all
platforms wasn't true any more, it goes via the common select
mechanism, so it doesn't matter if there's a usleep() library func or
not.


 -- Scheme Procedure: sleep secs
 -- Scheme Procedure: usleep usecs
 -- C Function: scm_sleep (secs)
 -- C Function: scm_usleep (usecs)
     Wait the given period SECS seconds or USECS microseconds (both
     integers).  If a signal arrives the wait stops and the return
     value is the time remaining, in seconds or microseconds
     respectively.  If the period elapses with no signal the return is
     zero.

     On most systems the process scheduler is not microsecond accurate
     and the actual period slept by `usleep' might be rounded to a
     system clock tick boundary, which could be 10 milliseconds.

     See `scm_std_sleep' and `scm_std_usleep' for equivalents at the C
     level (*note Blocking::).


 -- Scheme Procedure: getitimer which_timer
 -- Scheme Procedure: setitimer which_timer interval_seconds
          interval_microseconds periodic_seconds periodic_microseconds
 -- C Function: scm_getitimer (which_timer)
 -- C Function: scm_setitimer (which_timer, interval_seconds,
          interval_microseconds, periodic_seconds,
          periodic_microseconds)
     Get or set the periods programmed in certain system timers.  These
     timers count down from a value and upon reaching zero they raise a
     signal and optionally restart at a further programmed value (for
     periodic operation).  WHICH_TIMER is the timer to act on, one of
     the following values

      -- Variable: ITIMER_REAL
          A real-time timer, counting down elapsed real time.  At zero
          it raises `SIGALRM'.  This is like `alarm' above, but with a
          higher resolution period.

      -- Variable: ITIMER_VIRTUAL
          A virtual-time timer, counting down while the current process
          is actually using CPU.  At zero it raises `SIGVTALRM'.

      -- Variable: ITIMER_PROF
          A profiling timer, counting down while the process is running
          (like `ITIMER_VIRTUAL') and also while running system calls
          on the process's behalf.  At zero it raises a `SIGPROF'.

          This timer is intended for use profiling where a program is
          spending its time (by looking where it is when the timer goes
          off).

     `getitimer' returns the current timer value and its programmed
     restart value, as a list containing two pairs.  Each pair is a
     time in seconds and microseconds: `((INTERVAL_SECS .
     INTERVAL_USECS) (PERIODIC_SECS . PERIODIC_USECS))'.

     `setitimer' sets the timer values similarly, in seconds and
     microseconds (which must be integers).  The periodic value can be
     zero to have the timer run down just once.  The return value is
     the timer's previous setting, in the same form as `getitimer'
     returns.

          (setitimer ITIMER_REAL
                     5 500000     ;; first SIGALRM in 5.5 seconds time
                     2 0)         ;; then repeat every 2 seconds

     Although the timers are programmed in microseconds, the actual
     accuracy might not be that high.