NAME

uschedule - uschedule a job

SYNOPSIS

uschedule [OPTIONS] ID TIMESPEC [...]

DESCRIPTION

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).

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