.\"                                      Hey, EMACS: -*- nroff -*-
.TH SLEEPENH 1 "2008/04/20"
.\" 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
.RI [ initial\-time ]
.RI sleep\-time
.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 \fBinitial\-time\fP to a
successive execution of \fBsleepenh\fP.
.SH OPTIONS
There are no command line options. Run it without any option to
get a brief help and version.
.SH ARGUMENTS
\fBsleep\-time\fP is a real number in seconds,
with microseconds resolution (1 minute, 20 seconds and 123456
microseconds would be 80.123456).
.br
\fBinitial\-time\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 \fBinitial\-time\fP. Use the value supplied
by a previous execution of \fBsleepenh\fP.
.br
If you don't specify \fBinitial\-time\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 initial\-time +
sleep\-time 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 sleep\-times 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.