uschedule - uschedule a job
uschedule [OPTIONS] ID TIMESPEC [...]
uschedule 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).
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).
uschedule --from "2004-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.
The default is 3600 seconds (one hour).
uschedule --to "2004-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.
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.
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.
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.
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.
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".
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
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
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.
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.
Uwe Ohse, uwe@ohse.de
uschedulecmd(1), uschedule_intro(7).