\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename sleep-until.info
@settitle sleep-until
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Miscellaneous
@direntry
* sleep-until: (sleep-until).        Sleep until a specified time
@end direntry


@copying
Copyright @copyright{} 2015 Mattias Andrée

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@ifnottex
@node Top
@top sleep-until -- Sleep until a specified time
@insertcopying
@end ifnottex

@titlepage
@title sleep-until
@subtitle Sleep until a specified time
@author by Mattias Andrée (maandree)

@page
@c @center `'
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                        Brief overview of @command{sleep-until}.
* Invoking::                        Invocation of @command{sleep-until}.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

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

@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
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye