UTIMER(1)

NAME
utimer - command-line "timer" tool which features a timer, a countdown and a stopwatch.

SYNOPSIS
utimer [--timer=TIMELENGTH | -t TIMELENGTH] [--countdown=TIMELENGTH | -c TIMELENGTH] [--quiet | -q] [--verbose | -v] [--quit-with-success] utimer [--limits | -L] utimer [--version]

DESCRIPTION
utimer or µTimer (pronounced "micro-timer") is a multifunction timer (command-line only). It features a timer, a countdown, and a stopwatch. The timer counts the elapsed time, increasing to reach the given time length and then stops. Given a time length, the timer will "sleep", wait or pause till the time length has passed, then exits. Compared to the linux sleep function, µTimer actually shows the current elapsed time which can be useful for long time lengths. The countdown, compared to the timer, has the only difference that the starting point is the given time length and it will decrease to reach 0. When it reaches 0 (when the time length has passed), the program exits. It can be very useful for creating scripts. The stopwatch is like a real stopwatch where you can measure time of multiple events, or use it for (board) games, or anything else. It starts counting time when the program is started, and it can be stopped (using the 'Q' key) or otherwise you can just hit the ENTER key when you have to take multiple measures without stopping the counting.

OPTIONS

--help | -?
    Print the command line options.

--timer=TIMELENGTH | -t TIMELENGTH
    Shows a timer that runs until TIMELENGTH has passed. TIMELENGTH is a pattern that should look like: 2d15h39m58s120ms. See the Timer section in USAGE to read more about how to use the timer.

--countdown=TIMELENGTH | -c TIMELENGTH
    Shows a countdown that runs until TIMELENGTH has passed (until it reaches zero). TIMELENGTH is a pattern that should look like: 2d15h39m58s120ms. See the Countdown section in USAGE to read more about how to use the countdown.

--stopwatch | -s
    Starts the stopwatch that runs until it is stopped using the 'Q' key or by other means (Ctrl+C, system signals, ...). See the Stopwatch section in USAGE to read more about how to use the stopwatch.

--verbose | -v
    Print more information during the program's process. (note that if used with -q, this option is ignored)

--quiet | -q
    Quiet or silent output (almost no output) (note that if used with -v, -v is ignored).

--debug | -D
    Show debug information in output (should ONLY be used for bug reporting, for developers or for testing purposes).

--limits | -L
    Display the limits of µTimer for your machine (maximum values, longest timer, ...). It may be not be perfectly accurate. Use this option only to have an idea of what it can do.

--quit-with-success
    When you quit the program using the 'q' key, it will exit with a success exit status code, instead of an error one normally. (Note that 'ctrl+c' isn't affected by this option)

USAGE

Timer:
    utimer --timer=TIMELENGTH or utimer -t TIMELENGTH When using the timer, µTimer will show the current elapsed time and then will exit when TIMELENGTH is reached (read: when that TIMELENGTH has passed). The TIMELENGTH is composed of pairs of: a value + a suffix (for example "39d" for 39 days). It can be in any order, and there is no space between each pair. Each value must be a positive integer and can be null (0). The suffix is case sensitive (see below for the suffixes list). Here's a few valid examples of TIMELENGTH: 55s, 2m450ms, 0s, 0d32h, 9m7h30s80ms6d, 1d0h0m50s. Supported suffixes are: d for days, h for hours, m for minutes, s for seconds, ms for milliseconds.

Countdown:
    utimer --countdown=TIMELENGTH or utimer -c TIMELENGTH When using the countdown, µTimer will show the current remaining time before exiting. After TIMELENGTH has passed -or when the remaining time reaches zero (0)- µTimer exits. See the Timer usage to know how to write a valid TIMELENGTH.

Stopwatch:
    utimer --stopwatch or utimer -s When using the stopwatch, it counts until it is stopped using the 'Q' key or Ctrl+C or certain system signals (SIGKILL for example). You can use the ENTER key to take measures (like a snapshot) of the elapsed time.

SHORTCUT KEYS

'Q':
    You can stop/quit the timer whenever by using the 'Q' key, note that the program will exit with a error exit status code (1) (you can bypass this behaviour by using the --quit-with-success option, see the EXIT_STATUS section above).

SPACEBAR:
    You can pause the timer anytime using the spacebar key. To resume, just hit the spacebar again.

ENTER:
    With the stopwatch, you can use the ENTER key to take measures (like a snapshot) of the elapsed time.

EXIT STATUS
After the timer or the countdown are done, the program exits with a success exit status code (0). But when you quit during the timer/countdown is counting using 'q', it exits with an error exit status code (1). You can change this behaviour using the --quit-with-success option. (Note that 'ctrl+c' isn't affected by this option)

EXAMPLE

Timer:
    utimer -t 20s900ms runs the timer for 20 seconds and 900 milliseconds.

    utimer --timer=1d runs the timer for a whole day.

Countdown:
    utimer -c 1m48s500ms runs the countdown for 1 minute, 48 seconds and 500 milliseconds.

    utimer --countdown=2d5m runs the countdown for 2 days plus 5 minutes.

Stopwatch:
    utimer -s starts the stopwatch.

ACCURACY
The timer can be accurate enough for most common uses, and we cannot give any warranty on its accuracy. This is due to the time needed to start and to exit the program. On our test machines, it's as low as 5 milliseconds.

BUGS
If you find any bug using µTimer, please report it to: https://bugs.launchpad.net/utimer or send it to: bugs@utimer.codealpha.net

AUTHOR
Arnaud "Weboide" Soyez <weboide@codealpha.net>