GNUWATCH(1)

NAME
gnuwatch - execute a program periodically, showing output fullscreen

SYNOPSIS
gnuwatch [option ...] command

DESCRIPTION
gnuwatch (renamed from watch for the OpenBSD package) runs command repeatedly, displaying its output and errors (the first screenful). This allows you to watch the program output change over time. By default, command is run every 2 seconds and watch will run until interrupted. A header informs of the start and running time of command as well as its exit code.

OPTIONS

-b, --beep
    Beep if command has a non-zero exit.

-c, --color
    Interpret ANSI color and style sequences.

-C, --no-color
    Do not interpret ANSI color and style sequences.

-d, --differences[=permanent]
    Highlight the differences between successive updates. If the optional permanent argument is specified then watch will show all changes since the first iteration. The permanent argument needs to be linked to the option, such as -d1 or --differences=1.

-e, --errexit
    Freeze updates on command error, and exit after a key press. The exit code of watch will be the code command exits with. If signal n is the cause of command termination, the exit code will be 128 + n.

-f, --follow
    Instead of clearing the screen at each update, watch will scroll the output similiar to how tail -f works. This option is not compatible with any option tracking the output of the screen, such as the --differences, --chgexit and --eqexit options.

-g, --chgexit
    Exit when the visible output of command changes. Changes that are off the screen due to small screen size or large output will not cause watch to exit.

-n, --interval seconds
    Specify update interval. Values smaller than 0.1 and larger than 2678400 (31 days) are converted into these respective bounds. Both '.' and ',' work for any locale. The WATCH_INTERVAL environment variable can be used to persistently set a non-default interval (following the same rules and formatting).

-p, --precise
    Execute command --interval seconds after its previous run started, instead of --interval seconds after its previous run finished. If it's taking longer than --interval seconds for command to complete, it is waited for in either case.

-q, --equexit <cycles>
    Exit when output of command does not change for the given number of cycles.

-r, --no-rerun
    Do not run the program on terminal resize, the output of the program will re-appear at the next regular run time.

-s, --shotsdir
    Directory to save screenshots into.

-t, --no-title
    Turn off the header normally shown at the top of the screen.

-w, --no-wrap
    Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line.

-x, --exec
    Pass command to an exec(3) call instead of sh -c. The program will start a bit quicker. Shell features (environment setup, variable and pathname expansion, etc.) will be unavailable.

-h, --help
    Display help text and exit.

-v, --version
    Display version information and exit.

KEY CONTROL

spacebar
    Issue command immediately. If it's running at the moment, it is not interrupted and its next round will start without delay.

q   Quit watch. It currently does not interrupt a running command (as opposed to terminating signals, such as the SIGKILL following Ctrl+C).

s   Take a screenshot. It will be saved in the working directory, unless specified otherwise by --shotsdir. If command is running at the moment, the screenshot will be taken as soon as it finishes.

EXIT STATUS

0   Success. Does not represent command exit code.

1   Errors unrelated to command operation.

2   Errors related to command execution and management (not its exit code).

any non-zero (--errexit)
    With --errexit the last exit code of command is returned.

ENVIRONMENT
The behavior of watch is affected by the following environment variables.

WATCH_INTERVAL
    Update interval, follows the same rules as the --interval command line option.

COLUMNS
    Terminal screen character width. Set to override autodetection.

LINES
    Terminal screen character height. Set to override autodetection.

NOTES
POSIX option processing is used (i.e., option processing stops at the first non-option argument). This means that flags after command don't get interpreted by watch itself.

Non-printing characters are stripped from program output. Use cat -v as part of the command pipeline if you want to see them.

EXAMPLES

To watch the contents of a directory change, you could use

    gnuwatch -d ls -l

If you have CPUs with a dynamic frequency and want to observe it change, try the following. The command is passed to the shell, which allows you to make the pipeline. The quotes are a feature of the shell too.

    gnuwatch -n1 'grep "^cpu MHz" /proc/cpuinfo | sort -nrk4'

To monitor the up status of your servers, saving a copy of the output of each run to a file, you may use this. The -p makes the command execute every 10 seconds regardless of how long it took to complete the previous run.

    gnuwatch -n10 -p -d '{ date; for i in 10.0.0.31 10.0.0.32 10.0.0.33; do R=OK; ping -c2 -W2 "$i" &>/dev/null || R=FAIL; echo "$i: $R"; done } | tee -a ~/log'

You can watch for your administrator to install the latest kernel with

    gnuwatch uname -r

BUGS
When the terminal dimensions change, its contents changes are not registered on the next command run. --chgexit will not trigger that turn and the counter of --equexit will not restart even if command output changes meanwhile. --differences highlighting is reset.

REPORTING BUGS
Please send bug reports to procps@freelists.org.