Ubuntu Manpages

watch

execute a program periodically, showing output fullscreen

watch [option ...] command

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

Beep if command has a non-zero exit.
Interpret ANSI color and style sequences.
Do not interpret ANSI color and style sequences.
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.
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.
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.
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.
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).
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.
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.
Turn off the header normally shown at the top of the screen.
Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line.
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.
Display help text and exit.
Display version information and exit.

Issue command immediately. If it's running at the moment, it is not interrupted and its next round will start without delay.
Quit watch. It currently does not interrupt a running command (as opposed to terminating signals, such as the SIGKILL following Ctrl+C).
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.

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).
With --errexit the last exit code of command is returned.

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

Update interval, follows the same rules as the --interval command line option.
Terminal screen character width. Set to override autodetection.
Terminal screen character height. Set to override autodetection.

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.

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

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

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

watch -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

watch uname -r

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.

Please send bug reports to procps@freelists.org.