(Signals): Merge sleep and usleep, note usleep not

actually microsecond accurate, remove warning usleep not always
available (guile has own code for it now, it's not the system call).
Cross reference scm_std_sleep / scm_std_usleep.

(Signals): Merge getitimer and setitimer, describe what
each timer does, use @defvar to get them indexed, caution may not
actually be microsecond accurate.

doc/ref/posix.texi

@@ -1967,47 +1967,72 @@ action is to either terminate the current process or invoke a
 handler procedure.  The return value is unspecified.
 @end deffn
 
-@deffn {Scheme Procedure} sleep i
+@deffn {Scheme Procedure} sleep secs
-@deffnx {C Function} scm_sleep (i)
+@deffnx {Scheme Procedure} usleep usecs
-Wait for the given number of seconds (an integer) or until a signal
+@deffnx {C Function} scm_sleep (secs)
-arrives.  The return value is zero if the time elapses or the number
+@deffnx {C Function} scm_usleep (usecs)
-of seconds remaining otherwise.
+Wait the given period @var{secs} seconds or @var{usecs} microseconds
-@end deffn
+(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.
 
-@deffn {Scheme Procedure} usleep i
+On most systems the process scheduler is not microsecond accurate and
-@deffnx {C Function} scm_usleep (i)
+the actual period slept by @code{usleep} might be rounded to a system
-Sleep for @var{i} microseconds.  @code{usleep} is not available on
+clock tick boundary, which might be 10 milliseconds for instance.
-all platforms. [FIXME: so what happens when it isn't?]
-@end deffn
 
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
+See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
+the C level (@pxref{Blocking}).
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
-
-Return information about the timer's previous setting.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer.  The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
 @end deffn
 
 @deffn {Scheme Procedure} getitimer which_timer
+@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
 @deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}.
+@deffnx {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 have a current interval value which counts down and on reaching
+zero raises a signal.  An optional periodic value can be set to
+restart from there each time, for periodic operation.
+@var{which_timer} is one of the following values
 
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
+@defvar ITIMER_REAL
-and @code{ITIMER_PROF}.
+A real-time timer, counting down elapsed real time.  At zero it raises
+@code{SIGALRM}.  This is like @code{alarm} above, but with a higher
+resolution period.
+@end defvar 
 
-The return value will be a list of two cons pairs representing the
+@defvar ITIMER_VIRTUAL
-current state of the given timer.  The first pair is the seconds and
+A virtual-time timer, counting down while the current process is
-microseconds of the timer @code{it_interval}, and the second pair is
+actually using CPU.  At zero it raises @code{SIGVTALRM}.
-the seconds and microseconds of the timer @code{it_value}.
+@end defvar 
+
+@defvar ITIMER_PROF
+A profiling timer, counting down while the process is running (like
+@code{ITIMER_VIRTUAL}) and also while system calls are running on the
+process's behalf.  At zero it raises a @code{SIGPROF}.
+
+This timer is intended for profiling where a program is spending its
+time (by looking where it is when the timer goes off).
+@end defvar 
+
+@code{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: @code{((@var{interval_secs}
+. @var{interval_usecs}) (@var{periodic_secs}
+. @var{periodic_usecs}))}.
+
+@code{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 @code{getitimer} returns.
+
+@example
+(setitimer ITIMER_REAL
+           5 500000     ;; first SIGALRM in 5.5 seconds time
+           2 0)         ;; then repeat every 2 seconds
+@end example
+
+Although the timers are programmed in microseconds, the actual
+accuracy might not be that high.
 @end deffn