fcd97e6a62
--------------- Original Master Branch Commit Message: The manual page for watch for the exec option was confusing and backwards. Hopefully this one makes more sense. References: procps-ng/procps#75 Signed-off-by: Jim Warner <james.warner@comcast.net>
182 lines
4.3 KiB
Groff
182 lines
4.3 KiB
Groff
.TH WATCH 1 "2018-03-03" "procps-ng" "User Commands"
|
|
.SH NAME
|
|
watch \- execute a program periodically, showing output fullscreen
|
|
.SH SYNOPSIS
|
|
.B watch
|
|
[\fIoptions\fR] \fIcommand\fR
|
|
.SH DESCRIPTION
|
|
.B watch
|
|
runs
|
|
.I command
|
|
repeatedly, displaying its output and errors (the first screenfull). 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.
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-differences\fR [\fIpermanent\fR]
|
|
Highlight the differences between successive updates. Option will read
|
|
optional argument that changes highlight to be permanent, allowing to see what
|
|
has changed at least once since first iteration.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR
|
|
Specify update interval. The command will not allow quicker than 0.1 second
|
|
interval, in which the smaller values are converted. Both '.' and ',' work
|
|
for any locales.
|
|
.TP
|
|
\fB\-p\fR, \fB\-\-precise\fR
|
|
Make
|
|
.BR watch
|
|
attempt to run
|
|
.I command
|
|
every
|
|
.I interval
|
|
seconds. Try it with
|
|
.B ntptime
|
|
and notice how the fractional seconds stays (nearly) the same, as opposed to
|
|
normal mode where they continuously increase.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-no\-title\fR
|
|
Turn off the header showing the interval, command, and current time at the
|
|
top of the display, as well as the following blank line.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-beep\fR
|
|
Beep if command has a non-zero exit.
|
|
.TP
|
|
\fB\-e\fR, \fB\-\-errexit\fR
|
|
Freeze updates on command error, and exit after a key press.
|
|
.TP
|
|
\fB\-g\fR, \fB\-\-chgexit\fR
|
|
Exit when the output of
|
|
.I command
|
|
changes.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-color\fR
|
|
Interpret ANSI color and style sequences.
|
|
.TP
|
|
\fB\-x\fR, \fB\-\-exec\fR
|
|
Pass
|
|
.I command
|
|
to
|
|
.BR exec (2)
|
|
instead of
|
|
.B sh \-c
|
|
which reduces the need to use extra quoting to get the desired effect.
|
|
.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 "EXIT STATUS"
|
|
.PP
|
|
.RS
|
|
.PD 0
|
|
.TP
|
|
.B 0
|
|
Success.
|
|
.TP
|
|
.B 1
|
|
Various failures.
|
|
.TP
|
|
.B 2
|
|
Forking the process to watch failed.
|
|
.TP
|
|
.B 3
|
|
Replacing child process stdout with write side pipe failed.
|
|
.TP
|
|
.B 4
|
|
Command execution failed.
|
|
.TP
|
|
.B 5
|
|
Closing child process write pipe failed.
|
|
.TP
|
|
.B 7
|
|
IPC pipe creation failed.
|
|
.TP
|
|
.B 8
|
|
Getting child process return value with
|
|
.BR waitpid (2)
|
|
failed, or command exited up on error.
|
|
.TP
|
|
.B other
|
|
The watch will propagate command exit status as child exit status.
|
|
.SH NOTES
|
|
POSIX option processing is used (i.e., option processing stops at
|
|
the first non\-option argument). This means that flags after
|
|
.I command
|
|
don't get interpreted by
|
|
.BR watch
|
|
itself.
|
|
.SH BUGS
|
|
Upon terminal resize, the screen will not be correctly repainted until the
|
|
next scheduled update. All
|
|
.B \-\-differences
|
|
highlighting is lost on that update as well.
|
|
|
|
Non-printing characters are stripped from program output. Use "cat -v" as
|
|
part of the command pipeline if you want to see them.
|
|
|
|
Combining Characters that are supposed to display on the character at the
|
|
last column on the screen may display one column early, or they may not
|
|
display at all.
|
|
|
|
Combining Characters never count as different in
|
|
.I \-\-differences
|
|
mode. Only the base character counts.
|
|
|
|
Blank lines directly after a line which ends in the last column do not
|
|
display.
|
|
|
|
.I \-\-precise
|
|
mode doesn't yet have advanced temporal distortion technology to compensate
|
|
for a
|
|
.I command
|
|
that takes more than
|
|
.I interval
|
|
seconds to execute.
|
|
.B watch
|
|
also can get into a state where it rapid-fires as many executions of
|
|
.I command
|
|
as it can to catch up from a previous executions running longer than
|
|
.I interval
|
|
(for example,
|
|
.B netstat
|
|
taking ages on a DNS lookup).
|
|
.SH EXAMPLES
|
|
.PP
|
|
To watch for mail, you might do
|
|
.IP
|
|
watch \-n 60 from
|
|
.PP
|
|
To watch the contents of a directory change, you could use
|
|
.IP
|
|
watch \-d ls \-l
|
|
.PP
|
|
If you're only interested in files owned by user joe, you might use
|
|
.IP
|
|
watch \-d 'ls \-l | fgrep joe'
|
|
.PP
|
|
To see the effects of quoting, try these out
|
|
.IP
|
|
watch echo $$
|
|
.br
|
|
watch echo '$$'
|
|
.br
|
|
watch echo "'"'$$'"'"
|
|
.PP
|
|
To see the effect of precision time keeping, try adding
|
|
.I \-p
|
|
to
|
|
.IP
|
|
watch \-n 10 sleep 1
|
|
.PP
|
|
You can watch for your administrator to install the latest kernel with
|
|
.IP
|
|
watch uname \-r
|
|
.PP
|
|
(Note that
|
|
.I \-p
|
|
isn't guaranteed to work across reboots, especially in the face of
|
|
.B ntpdate
|
|
or other bootup time-changing mechanisms)
|