uschedule(1)uschedule(1)NAMEuschedule - uschedule a job
SYNOPSISuschedule [OPTIONS] ID TIMESPEC [...]
DESCRIPTIONuschedule schedules the command with the identifier ID to be executed
at the time specified by TIMESPEC. Multiple TIMESPEC arguments are
allowed.
ID is the identifier of a command previously registered with
uschedulecmd(1).
OPTIONS-., --dot-as-home
The current working directory will be used instead of $HOME.
-1, --null1
Redirect the standard output of the job to /dev/null. The
default is to write it into the log file of the uscheduled(8)
daemon.
-2, --null2
Redirect the standard error output of the job to /dev/null. The
same default applies.
-c, --count=NNN
Repeat the command up to NNN times. A value of 1 means the the
job will run once, 0 is a synonym for forever, which is the
default.
-d, --dir=DIR
Put the new job into DIR. The default is ~/.uschedule/.
-D, --description=DESC
Give the new job the description DESC. The description is used
for the user interface commands uschedulelist(1) and
uschedulerm(1) only. Descriptions must not be longer than 70
characters and must not contain colons.
-e, --every=NUMBER[mhdw]
Repeat every NUMBER time units (default: seconds).
This option is implemented in such a way that the NUMBER is
added once at the start of a search. Then all other restrictions
(late, from, to, TIMESPEC) will be applied and the next matching
time will be searched for. In other words: The start time to be
searched from is changed from now to now + NUMBER.
A m (h, d or w) appended to NUMBER changes the time unit from
seconds to minutes (hours, days or weeks).
-f, --from=TIMESPEC
Jobs will only be started if TIMESPEC has matched. This together
with the --to option allows to further restrict the times a job
will be started. This example starts a job JOBID every day a few
seconds after midnight, but only after the first of april, 2004,
has been reached:
uschedule--from "2003-4-1 00:00:00" JOBID '*-*-* 00:00:10'
TIMESPEC should be simple. Wild cards are only allowed at the
start, not after any fixed number. 2002-*-1 00:00:00 is
forbidden, *-*-* *:00:00 is OK.
Weekday names may be used, too, though the result is likely to
be non-intuitive. Better avoid them.
This option was added in version 0.6.0.
-l, --late=SECONDS
Allow the job to be executed up to SECONDS late. This is useful
if the machine or the uscheduled(8) daemon was down during the
time the job should have run.
The default is 3600 seconds (one hour).
-t, --to=TIMESPEC
Jobs will only be started if TIMESPEC has not been reached. This
together with the --from option allows to further restrict the
times a job will be started. The example below starts a job
every day a few seconds after midnight, but only up to 30th of
march, 2004:
uschedule--to "2003-4-1 00:00:00" jobid '*-*-* 00:00:10'
TIMESPEC should be simple. Wild cards are only allowed at the
start, not after any fixed number. 2002-*-1 00:00:00 is
forbidden, *-*-* *:00:00 is OK. If wild cards are used, the
--from option has to be used, to.
Weekday names may be used, too, though the result is likely to
be non-intuitive. Better avoid them.
This option was added in version 0.6.0.
TIMESPEC
A time specification consists of two or three words. The first,
optional, words specifies a day-of-week, the next the year, month and
day-of-month, and the last word specifies hour, minute and seconds.
Words are separated by exactly one space.
Day Of Week
The day of the week is given as a comma separated list of weekday names
or three letter abbreviations thereof. Names are case insensitive. The
default is to run the job at any day of the week.
Sunday,Wed is a valid list. Monday, Tues isn't.
Date
The date consists of three parts: Year, month and day. Two parts are
separated by a single dash. Each part is a numerical value as described
below.
Time
The time consists of three parts, too. Hour, minute and second are by a
single colon. Each part is a numerical value as described below.
Number Specification
Whenever is number is allowed in a job execution time specification is
may be either a single value, a single star ("*", meaning "all possible
values") or a comma separated list of values.
A value may be a number or a number ("a") followed by a slash followed
by a number ("b"), meaning "execute at 'a+b*n'", where "n" is a
positive integer including 0). You may use a plus sign instead of the
slash ('a+b').
Note that 30/10 (oder 30+10) and such things are understood quite
literally, meaning "30, 40, 50" and not "0, 10, 20, 30, 40, 50".
Examples
The following schedules a job to be run at midnight of each seventh of
the month:
*-*-7 00:00:00
To run a job on every monday in december at 12:00:00:
Monday *-12-* 12:00:00
To run a job 30 minutes and 45 seconds after each full hour on every
monday and friday if that day is the first or third day of the month in
the months january, march, may, juli, september and november:
mon,fri *-1/2-1,3 *:30:45
Incomplete time specs
uschedule attempts to complete the TIMESPECs, except for the --from or
--to ones. *- is used when year or month is missing, * is used when the
day is missing, and *: is used when hour or minute are missing. If
there is no time given at all, then 0:0:0 is used. Examples:
03-05 08:05:40 -> *-03-05 08:05:40
05 08:05:40 -> *-*-05 08:05:40
08:05:40 -> *-*-* 08:05:40
05:40 -> *-*-* *:05:40
40 -> *-*-* *:*:40
Sat,Sun 05 08:05:40 -> Sat,Sun *-*-05 08:05:40
Sat,Sun 08:05:40 -> Sat,Sun *-*-* 08:05:40
2003-03-05 05:40 -> 2003-03-05 *:05:40
2003-03-05 -> 2003-03-05 0:0:0
03-05 -> *-03-05 0:0:0
TIME OFFSET
An argument consisting of a plus sign and one to four numbers separated
by colons (+[[[dd:]hh:]mm:]ss) means to start the job once in the
future, at the time reached with the current time is added to the
argument. dd is the offset in days, hh in hours, mm in minutes und ss
stands for seconds. That is,
uschedule test +1:0:0:0
uschedule test +24:0:0
uschedule test +1440:0
uschedule test +86400
all start the job "test" exactly one day after uschedule is executed.
DIFFERENCES
The unix cron daemon executes a job if either day or week or day of
month matches. uscheduled(8) executes it if both match. The is no way
to completely mimic either logic with the other software.
Unix cron often needs a separated at daemon to execute one-time-jobs.
This is nothing more than a design problem in cron.
Unix also provides a batch command, which executes jobs if the system
load is low. This is often implemented inside the at daemon. uschedule
doesn't provide a way to emulate this (note that batch is pointless
anyway: if you just have a short job then you might as well run it, it
doesn't matter. If you have a long and resource-intensive job and don't
want your job to eat resources when there's a shortage of them then
batch provides no way to temporarily suspend a job during this time.
If the resource in question is not system load but memory, disk- or
network-bandwidth then batch doesn't help you).
Unix cron doesn't support second granularity. uschedule does this for
only one reason: to help to avoid that all jobs of all users start in
the same second and overload the system.
AUTHOR
Uwe Ohse, uwe@ohse.de
SEE ALSOuschedulecmd(1), uschedule_intro(7).
The homepage may be more up-to-date, see
http://www.ohse.de/uwe/uschedule.html.
uschedule 0.7.1 uschedule(1)
