watch(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | KEY CONTROL | EXIT STATUS | ENVIRONMENT | NOTES | EXAMPLES | BUGS | REPORTING BUGS | COLOPHON

WATCH(1)                      User Commands                     WATCH(1)

NAME         top

       watch - execute a program periodically, showing output fullscreen

SYNOPSIS         top

       watch [option ...] command

DESCRIPTION         top

       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.

OPTIONS         top

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

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

       -g, --chgexit
              Exit when the output of command changes.

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

       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         top

       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         top

       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         top

       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         top

       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

BUGS         top

       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         top

       Please send bug reports to ⟨procps@freelists.org⟩.

COLOPHON         top

       This page is part of the procps-ng (/proc filesystem utilities)
       project.  Information about the project can be found at 
       ⟨https://gitlab.com/procps-ng/procps⟩.  If you have a bug report
       for this manual page, see
       ⟨https://gitlab.com/procps-ng/procps/blob/master/Documentation/bugs.md⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://gitlab.com/procps-ng/procps.git⟩ on 2024-06-14.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2024-06-04.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

procps-ng                      2023-07-31                       WATCH(1)

Pages that refer to this page: lsblk(8)