about summary refs log tree commit diff
path: root/snooze.1
blob: ee35c7883c3c57d1d7a3bdd062bc29d195161883 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
.Dd January 4, 2016
.Dt SNOOZE 1
.Os
.Sh NAME
.Nm snooze
.Nd run a command at a particular time
.Sh SYNOPSIS
.Nm
.Op Fl nv
.Op Fl t Ar timefile
.Op Fl T Ar timewait
.Op Fl R Ar randdelay
.Op Fl s Ar slack
.Op Fl d Ar day
.Op Fl m Ar mon
.Op Fl w Ar wday
.Op Fl D Ar yday
.Op Fl W Ar yweek
.Op Fl H Ar hour
.Op Fl M Ar min
.Op Fl S Ar sec
.Ar command\ ...
.Sh DESCRIPTION
.Nm
waits until a particular time and then runs a command.
Together with a service supervision system such as
.Xr runsv 8 ,
this can be used to replace
.Xr cron 8 .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl n
Dry run: print the next 5 times the command would run and exit.
.It Fl v
Verbose: print scheduled (and rescheduled) times.
.It Fl t , Fl T
See below,
.Sx TIMEFILES .
.It Fl R
Wait randomly up to
.Ar randdelay
seconds later than the scheduled time.
.It Fl s
Commands are executed even if they are
.Ar slack
(default: 60) seconds late.
.El
.Pp
The durations
.Ar randdelay
and
.Ar slack
and
.Ar timewait
are parsed as seconds,
unless a postfix of
.Cm m
for minutes,
.Cm h
for hours, or
.Cm d
for days is used.
.Pp
The remaining arguments are patterns for the time fields:
.Pp
.Bl -tag -compact -width xxxxxxxxxx
.It Fl d
day of month
.It Fl m
month
.It Fl w
weekday (0-7, sunday is 0 and 7)
.It Fl D
day of year (1..366)
.It Fl W
ISO week of year (1..53)
.It Fl H
hour
.It Fl M
minute
.It Fl S
second
.El
.Pp
The following syntax is used for these options:
.Bl -tag -width xxxxxxxxxx
.It Cm -d 3
exact match: run on the 3rd
.It Cm -d 3,10,27
alternation: run on 3rd, 10th, 27th
.It Cm -d 1-5
range: run on 1st, 2nd, 3rd, 4th, 5th
.It Cm -d *
star: run every day
.It Cm -d /5
repetition: run on 5th, 10th, 15th, 20th, 25th, 30th day
.It Cm -d 2/5
shifted repetition: run on 7th, 12th, 17th, 22nd, 27th day
.El
.Pp
and combinations of those, e.g.\&
.Cm -d 1-10,15/5,28 .
.Pp
The defaults are
.Cm -d* -m* -w* -D* -W* -H0 -M0 -S0 ,
that is, every midnight.
.Pp
Note that
.Em all
patterns need to match
(contrary to
.Xr cron 8
where either day of month
.Em or
day of week matches), so
.Cm -w5 -d13
only runs on Friday the 13th.
.Pp
If
.Nm
receives a
.Dv SIGALRM
signal, the command is immediately executed.
.Sh TIMEFILES
Optionally, you can keep track of runs in time files, using
.Fl t :
.Pp
When
.Fl T
is passed, execution will not start earlier than the mtime
of
.Ar timefile
plus
.Ar timewait
seconds.
.Pp
When
.Fl T
is
.Em not
passed,
.Nm
will start finding the first matching time
starting from the mtime of
.Ar timefile ,
and taking
.Ar slack
into account.
(E.g.\&
.Cm -H0 -s 1d -t timefile
will start an instant
execution when timefile has not been touched today, whereas without
.Fl t
this would always wait until next midnight.)
.Pp
If
.Ar timefile
does not exist, it will be assumed outdated enough to
ensure earliest execution.
.Pp
.Nm
does not update the timefiles, your job needs to do that!
Only mtime is looked at, so
.Xr touch 1
is good.
.Sh EXIT STATUS
.Ex -std
.Pp
The
.Ar command
is run using exec, so its exit status gets propagated to the parent.
.Pp
If no command was given,
.Nm
just returns with status 0.
.Sh SEE ALSO
.Xr runwhen 1 ,
.Xr sleep 1 ,
.Xr uschedule 1 ,
.Xr cron 8
.Sh AUTHORS
.An Leah Neukirchen Aq Mt leah@vuxu.org
.Sh LICENSE
.Nm
is in the public domain.
.Pp
To the extent possible under law,
the creator of this work
has waived all copyright and related or
neighboring rights to this work.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/