From 72b2291551712d6182c798b23884bf50f2cf244e Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Tue, 10 Nov 2015 01:31:04 +0100 Subject: update doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- doc/info/sleep-until.texinfo | 48 +++++++++++++++++++++++++++++++++++--------- doc/man/sleep-until.1 | 29 ++++++++++++++++++++++++-- 2 files changed, 66 insertions(+), 11 deletions(-) (limited to 'doc') 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. -- cgit v1.2.3-70-g09d2