.\"                                      Hey, EMACS: -*- nroff -*-
.TH SLEEPENH 1 "November 2014" "sleepenh" "User commands"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
sleepenh \- an enhanced sleep program
.SH SYNOPSIS
.B sleepenh
[[\fI\,--warp|-w\/\fR] \fI\,INITIALTIME\/\fR] \fI\,TIMETOSLEEP\/\fR
.SH DESCRIPTION
\fBsleepenh\fP is a program that can be used when there is a need
to execute some functions periodically in a shell script. It was
not designed to be accurate for a single sleep, but to be
accurate in a sequence of consecutive sleeps.
.br
After a successful execution, it returns to stdout the timestamp
it finished running, that can be used as \fBINITIALTIME\fP to a
successive execution of \fBsleepenh\fP.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
display this help and exit
.TP
\fB\-w\fR, \fB\-\-warp\fR
warp resulting timestamp, when there is no need
to sleep.  An immediately following call of
sleepenh with the resulting TIMESTAMP would
most probably result in a real sleep.
.TP
\fB\-V\fR, \fB\-\-version\fR
output version information and exit
.SH ARGUMENTS
\fBTIMETOSLEEP\fP is a real number in seconds,
with microseconds resolution (1 minute, 20 seconds and 123456
microseconds would be 80.123456).
.br
\fBINITIALTIME\fP is a real number in seconds, with microseconds
resolution. This number is system dependent. In GNU/Linux systems,
it is the number of seconds since midnight 1970\-01\-01 GMT. Do not
try to get a good value of \fBINITIALTIME\fP. Use the value supplied
by a previous execution of \fBsleepenh\fP.
.br
If you don't specify \fBINITIALTIME\fP, it is assumed the current time.
.SH EXIT STATUS
An exit status greater or equal to 10 means failure.
Known exit status:
.TP
.B 0
Success.
.TP
.B 1
Success. There was no need to sleep. (means that INITIALTIME +
TIMETOSLEEP was greater than current time).
.TP
.B 10
Failure. Missing command line arguments.
.TP
.B 11
Failure. Did not receive SIGALRM.
.TP
.B 12
Failure. Argument is not a number.
.TP
.B 13
Failure. System error, could not get current time.
.SH USAGE EXAMPLE
Suppose you need to send the char 'A' to the serial port ttyS0
every 4 seconds. This will do that:
.RS   
 #!/bin/sh
 TIMESTAMP=$(sleepenh 0)
 while true; do
   # send the byte to ttyS0
   echo \-n "A" > /dev/ttyS0;
  
   # just print a nice message on screen
   echo \-n "I sent 'A' to ttyS0, time now is ";
   sleepenh 0;

   # wait the required time     
   TIMESTAMP=$(sleepenh $TIMESTAMP 4.0);
 done
.RE   
.SH HINT
This program can be used to get the current time. Just execute:
.TP
sleepenh 0
.SH BUGS
It is not accurate for a single sleep. Short TIMETOSLEEPs will also not
be accurate.
.SH SEE ALSO
.BR date (1),
.BR sleep (1).
.br
.SH AUTHOR
This manual page was written by Pedro Zorzenon Neto.