update doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

2 files changed, 66 insertions, 11 deletions

diff --git a/doc/info/sleep-until.texinfo b/doc/info/sleep-until.texinfo
index 7c1792a..445b2e0 100644
--- a/doc/info/sleep-until.texinfo
+++ b/doc/info/sleep-until.texinfo
@@ -61,26 +61,56 @@ Texts. A copy of the license is included in the section entitled
 @node Overview
 @chapter Overview
 
-Sleeps until a specified time.
+Sleeps until a specified time. @command{sleep-until}
+only supports the time to be specified by number of
+seconds (and nanoseconds) since an epoch. The program
+supports multiple clocks: all clocks supported by
+timerfd.
 
 
 
 @node Invoking
 @chapter Invoking
 
-If invoked without any arguments, the programs
-will exit with exit value 0. Otherwise, the
-highest argument argument is select. They should
-be integers or floating-point values. The process
-will sleep until the selected time has been reached,
-and will not stop even if interrupted. The time
-should be specified as the number of seconds since
-Epoch (1970-(01)Jan-01), in UTC bt not accounting
+@command{sleep-until} takes any number of arguments,
+of two classes: clock name and time point. The last
+specified clock name and the highest time point will
+be used. The time point may be a floating-point number.
+
+If no time point is specified, the program will exit
+with exit value 0. Otherwise the process will terminate,
+with exit value 0, when the selected time has been
+reached.
+
+Note that it is not possible to wait on two or more
+clocks at the same time. Rather, you need invoke
+@command{sleep-until} multiple times with different
+clocks. This is because the order of the arguments
+must not be important.
+
+By default, the clock @code{CLOCK_REALTIME} is used.
+In this case, the process will terminate at the
+selected number of seconds of the Epoch
+(1970-(01)Jan-01 00:00:00), in UTC but not accounting
 for leap seconds.
 
 Some versions of @command{date} can be used to
 specify the time point in a convenient manner.
 
+The clock is select by the name of the clock.
+On Linux 4.2.2 the clock that can be used are:
+@itemize @bullet{}
+@item @code{CLOCK_REALTIME}
+@item @code{CLOCK_MONOTONIC}
+@item @code{CLOCK_BOOTTIME}
+@item @code{CLOCK_REALTIME_ALARM}
+@item @code{CLOCK_BOOTTIME_ALARM}
+@end itemize
+@noindent
+Note that the neither course clocks, @code{CLOCK_MONOTONIC_RAW}
+(the proper implementation of a monotonic clock), and
+@code{CLOCK_TAI} does not work.
+
 
 
 @node GNU Free Documentation License
diff --git a/doc/man/sleep-until.1 b/doc/man/sleep-until.1
index 7567eb4..6672fcf 100644
--- a/doc/man/sleep-until.1
+++ b/doc/man/sleep-until.1
@@ -3,12 +3,36 @@
 sleep-until - sleeps until a specified time
 .SH SYNOPSIS
 .B sleep-until
+.IR clockname ...
 .IR timepoint ...
 .SH DESCRIPTION
 Pause until \fItimepoint\fP. \fItimepoint\fP is the number of
-seconds since Epoch, in UTC but not accounting for leap seconds.
+seconds since Epoch, in UTC but not accounting for leap seconds,
+by default. If \fIclockname\fP is specifed, \fItimepoint\fP is
+the number of seconds since the zerotime of that clock.
 \fItimepoint\fP may be an arbitrary floating point number.
 Pause is continued when interrupted.
+.PP
+On Linux 4.2.2 the clocks that can be used are:
+.TP
+*
+\fBCLOCK_REALTIME\fP
+.TP
+*
+\fBCLOCK_MONOTONIC\fP
+.TP
+*
+\fBCLOCK_BOOTTIME\fP
+.TP
+*
+\fBCLOCK_REALTIME_ALARM\fP
+.TP
+*
+\fBCLOCK_BOOTTIME_ALARM\fP
+.PP
+Note that the neither course clocks, \fBCLOCK_MONOTONIC_RAW\fP
+(the proper implementation of a monotonic clock), and
+\fBCLOCK_TAI\fP does not work.
 .SH EXIT STATUS
 .TP
 0
@@ -18,7 +42,8 @@ The command was successful.
 The command failed.
 .SH SEE ALSO
 .BR sleep (1),
-.BR date (1)
+.BR date (1),
+.BR clock_gettime (3)
 .SH AUTHORS
 Principal author, Mattias Andrée.  See the COPYING file for the full
 list of authors.