1=head1 NAME
2
3delay - counts down a specified number of seconds.
4
5=head1 SYNOPSIS
6
7  delay [options] <length> [-- command]
8  delay [options] until <timespec> [-- command]
9
10=head1 DESCRIPTION
11
12The delay program counts down a length of time specified on
13the command line. By default, it prints out the time remaining
14once a second. The rate and style of printing can be controlled
15using options to the program. This includes the ability to
16supress the printing entirely. It also somewhat supports delaying
17for fractional seconds.
18
19Delay attempts to compensate for the time it spends printing the
20updates. There should be no error that is a multiple of the
21time spent delaying. (There is a bit of error on the startup
22and termination of the program, but that's unavoidable.)
23
24There are several ways that the time to delay can be
25specified. The first is that it can be specified as an absolute length
26of time to delay. This can be in several formats. All of the following
27formats are allowable. (And equivalent.)
28
29  delay 1d 2:03:04.5
30  delay 1d 2h 3m 4.5s
31  delay 93785.5
32
33Please note that the fractional seconds code will only work for actual
34fractional seconds. So, doing things like '0.5h' will delay for half
35a second, and not for half an hour as one may expect. (But don't rely
36on this behavior, as it may change in future versions.)
37
38The second format is for a time to delay until be specified. The
39time parsing code is derived from that used it at, and as a result
40the time specifications should be described on L<at(1)>. For example:
41
42  delay until 4 pm
43  delay until noon tomorrow
44  delay until midnight 13 september 2000
45  delay until now + 5 minutes
46
47Please note that the parsing code has a resolution of a minute. So, the
48last specification would calculate the 5 minutes from the beginning of
49the current minute, and delay to that absolute point in time. If you need
50more precision, you can use the first time format, which allows an
51the delay length to be specified precisely.
52
53If delay sees "--" while parsing it's command line, it stops argument
54processing. Instead, the argument after the "--" is interpreted as a
55command to be run when delay completes, and any further arguments are
56used as arguments to that command. For example:
57
58  delay until 9:30 -- cdplay
59
60=head1 OPTIONS
61
62Delay allows you to use command line options to control aspects of its
63behavior. Here's a list:
64
65=over 4
66
67=item -q
68
69This enables quiet mode. This prevents delay from outputting the
70time remaining as it usually does. (This is the default if
71delay is called with "sleep" as part of the program name.)
72
73=item -m
74
75This enables a minimalistic count of the time remaining, with only the
76number of seconds left being displayed. This was the default for delay
771.0.
78
79=item -d
80
81This enables the default display. The day, hour, minute, and second are
82all broken out into seperate entrys. (This is the default, except for the
83cases where -q is the default.)
84
85=item -v
86
87This enables a more verbose mode of display. (It adds some explanitory
88text, as compared to -d.)
89
90=item -c
91
92This allows you to specify a custom time prompt. Printf-style formatting
93is performed, with the following being allowed as the possible percent
94substitutions:
95
96  %d	 Days remaining
97  %h	 Hours remaining (modulo 24)
98  %m	 Minutes remaining (modulo 60)
99  %s 	 Seconds remaining (modulo 60)
100  %n 	 Total seconds remaining
101
102For best results, you'll want to make sure that your custom format stays
103the same length throughout the count. Printf-style formatting is done
104on these codes. Use of percent-codes other than the ones listed above
105will lead to undefined behavior. (Crashes, usually.)
106
107The following escapes are also supported:
108
109  \n     Newline
110  \r     Carriage Return
111  \b     Backspace
112  \\     Backslash
113  \%     Percent
114
115Since the custom format no longer implicitly begins with a carriage return,
116it usually makes sense to either begin a custom code with \r or end it
117with \n.
118
119The standard formats can be expressed as custom codes. Here's a list of
120translations.
121
122  -m	\r% 8n
123  -d	\r% 3d %02h:%02m:%02s
124  -v	\rTime Remaining: %d days, %02h:%02m:%02s.
125
126=item -C
127
128This option enables the display of time remaining in big ugly curses
129numerals. This only displays the hours, minutes, and seconds
130remaining, although the number of hours to go may range above 24.
131
132=item -u
133
134This option takes a single parameter, the time in seconds between
135updates of the time remaining. It need not be a factor of the
136delay length. It defaults to 1 second, and must be at least that
137value.
138
139=item -b
140
141If this option is given, a bell character will be sent when time
142expires. This may be useful in cases where an xterm is send to
143de-iconify on a bell.
144
145=item -V
146
147If given, delay will display it's version and a short copyright message,
148and will then exit.
149
150=back
151
152=head1 BUGS
153
154The default format is only good for delays of less than 1000 days.
155
156Improper use of the -c option can lead to various problems, and may
157even have some security implications.
158
159execvp(2) is used to run the command, and this may run programs
160in the current directory rather than fully respecting your path. Please
161see L<execvp(2)> for more details.
162
163=head1 AUTHOR
164
165Tom Rothamel <tom-delay@onegeek.org>
166
167=head1 WEB SITE
168
169The delay web site is located at:
170
171	http://onegeek.org/~tom/software/delay/
172
173=head1 SEE ALSO
174
175L<sleep(1)>, L<printf(3)>, L<at(1)>
176