.\" .\" Copyright (c) 2023 Roman Žilka .\" Copyright (c) 2009-2024 Craig Small .\" Copyright (c) 2018-2023 Jim Warner .\" Copyright (c) 2011-2012 Sami Kerola .\" Copyright (c) 2003 Albert Cahalan .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" .TH WATCH 1 2024-07-19 procps-ng .SH NAME watch \- execute a program periodically, showing output fullscreen .SH SYNOPSIS .B watch .RI [ option " .\|.\|.\&]" .I command .SH DESCRIPTION .B watch runs .I command repeatedly, displaying its output and errors (the first screenful). This allows you to watch the program output change over time. By default, \fIcommand\fR is run every 2 seconds and \fBwatch\fR will run until interrupted. A header informs of the start and running time of \fIcommand\fR as well as its exit code. .SH OPTIONS .TP \fB\-b\fR, \fB\-\-beep\fR Beep if \fIcommand\fR has a non-zero exit. .TP \fB\-c\fR, \fB\-\-color\fR Interpret ANSI color and style sequences. .TP \fB\-C\fR, \fB\-\-no-color\fR Do not interpret ANSI color and style sequences. .TP \fB\-d\fR, \fB\-\-differences\fR[=\fIpermanent\fR] Highlight the differences between successive updates. If the optional \fIpermanent\fR argument is specified then \fBwatch\fR will show all changes since the first iteration. .TP \fB\-e\fR, \fB\-\-errexit\fR Freeze updates on \fIcommand\fR error, and exit after a key press. The exit code of \fBwatch\fR will be the code \fIcommand\fR exits with. If signal \fBn\fR is the cause of \fIcommand\fR termination, the exit code will be 128 + \fBn\fR. .TP \fB\-g\fR, \fB\-\-chgexit\fR Exit when the visible output of \fIcommand\fR changes. Changes that are off the screen due to small screen size or large output will not cause \fBwatch\fR to exit. .TP \fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR 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 \fBWATCH_INTERVAL\fR environment variable can be used to persistently set a non-default interval (following the same rules and formatting). .TP \fB\-p\fR, \fB\-\-precise\fR Execute \fIcommand\fR \fB\-\-interval\fR seconds after its previous run started, instead of \fB\-\-interval\fR seconds after its previous run finished. If it's taking longer than \fB\-\-interval\fR seconds for \fIcommand\fR to complete, it is waited for in either case. .TP \fB\-q\fR, \fB\-\-equexit\fR Exit when output of \fIcommand\fR does not change for the given number of cycles. .TP \fB\-r\fR, \fB\-\-no-rerun\fR Do not run the program on terminal resize, the output of the program will re-appear at the next regular run time. .TP \fB-s\fR, \fB--shotsdir\fR Directory to save screenshots into. .TP \fB\-t\fR, \fB\-\-no\-title\fR Turn off the header normally shown at the top of the screen. .TP \fB\-w\fR, \fB\-\-no\-wrap\fR Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line. .TP \fB\-x\fR, \fB\-\-exec\fR Pass \fIcommand\fR to an .BR exec (3) call instead of \fBsh \-c\fR. The program will start a bit quicker. Shell features (environment setup, variable and pathname expansion, etc.) will be unavailable. .TP \fB\-h\fR, \fB\-\-help\fR Display help text and exit. .TP \fB\-v\fR, \fB\-\-version\fR Display version information and exit. .SH "KEY CONTROL" .TP .B spacebar Issue \fIcommand\fR immediately. If it's running at the moment, it is not interrupted and its next round will start without delay. .TP .B q Quit \fBwatch\fR. It currently does not interrupt a running \fIcommand\fR (as opposed to terminating signals, such as the SIGKILL following Ctrl+C). .TP .B s Take a screenshot. It will be saved in the working directory, unless specified otherwise by \fB\-\-shotsdir\fR. If \fIcommand\fR is running at the moment, the screenshot will be taken as soon as it finishes. .SH "EXIT STATUS" .TP .B 0 Success. Does not represent \fIcommand\fR exit code. .TP .B 1 Errors unrelated to \fIcommand\fR operation. .TP .B 2 Errors related to \fIcommand\fR execution and management (not its exit code). .TP .B any non-zero (\-\-errexit) With \fB\-\-errexit\fR the last exit code of \fIcommand\fR is returned. .SH ENVIRONMENT The behavior of \fBwatch\fR is affected by the following environment variables. .TP .B WATCH_INTERVAL Update interval, follows the same rules as the \fB\-\-interval\fR command line option. .TP .B COLUMNS Terminal screen character width. Set to override autodetection. .TP .B LINES Terminal screen character height. Set to override autodetection. .SH NOTES POSIX option processing is used (i.e., option processing stops at the first non\-option argument). This means that flags after \fIcommand\fR don't get interpreted by \fBwatch\fR itself. .P Non-printing characters are stripped from program output. Use \fBcat -v\fR as part of the command pipeline if you want to see them. .SH EXAMPLES .PP To watch the contents of a directory change, you could use .IP watch \-d ls \-l .PP 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. .IP watch \-n1 'grep "^cpu MHz" /proc/cpuinfo | sort -nrk4' .PP 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 \fB\-p\fR makes the command execute every 10 seconds regardless of how long it took to complete the previous run. .IP 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' .PP You can watch for your administrator to install the latest kernel with .IP watch uname \-r .SH BUGS When the terminal dimensions change, its contents changes are not registered on the next \fIcommand\fR run. \fB\-\-chgexit\fR will not trigger that turn and the counter of \fB\-\-equexit\fR will not restart even if \fIcommand\fR output changes meanwhile. \fB\-\-differences\fR highlighting is reset. .SH "REPORTING BUGS" Please send bug reports to .MT procps@freelists.org .ME .