man-pages/man1/watch.1.html
2021-03-31 01:06:50 +01:00

277 lines
6.1 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of WATCH</TITLE>
</HEAD><BODY>
<H1>WATCH</H1>
Section: User Commands (1)<BR>Updated: 2018-03-03<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
watch - execute a program periodically, showing output fullscreen
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B>watch</B>
[<I>options</I>] <I>command</I>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
<B>watch</B>
runs
<I>command</I>
repeatedly, displaying its output and errors (the first screenfull). This
allows you to watch the program output change over time. By default,
<I>command</I> is run every 2 seconds and <B>watch</B> will run until interrupted.
<A NAME="lbAE">&nbsp;</A>
<H2>OPTIONS</H2>
<DL COMPACT>
<DT id="1"><B>-d</B>, <B>--differences</B> [<I>permanent</I>]<DD>
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.
<DT id="2"><B>-n</B>, <B>--interval</B> <I>seconds</I><DD>
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.
<DT id="3"><B>-p</B>, <B>--precise</B><DD>
Make
<B>watch</B>
attempt to run
<I>command</I>
every
<I>interval</I>
seconds. Try it with
<B>ntptime</B>
and notice how the fractional seconds stays (nearly) the same, as opposed to
normal mode where they continuously increase.
<DT id="4"><B>-t</B>, <B>--no-title</B><DD>
Turn off the header showing the interval, command, and current time at the
top of the display, as well as the following blank line.
<DT id="5"><B>-b</B>, <B>--beep</B><DD>
Beep if command has a non-zero exit.
<DT id="6"><B>-e</B>, <B>--errexit</B><DD>
Freeze updates on command error, and exit after a key press.
<DT id="7"><B>-g</B>, <B>--chgexit</B><DD>
Exit when the output of
<I>command</I>
changes.
<DT id="8"><B>-c</B>, <B>--color</B><DD>
Interpret ANSI color and style sequences.
<DT id="9"><B>-x</B>, <B>--exec</B><DD>
Pass
<I>command</I>
to
<B><A HREF="/cgi-bin/man/man2html?2+exec">exec</A></B>(2)
instead of
<B>sh -c</B>
which reduces the need to use extra quoting to get the desired effect.
<DT id="10"><B>-h</B>, <B>--help</B><DD>
Display help text and exit.
<DT id="11"><B>-v</B>, <B>--version</B><DD>
Display version information and exit.
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>EXIT STATUS</H2>
<P>
<DL COMPACT><DT id="12"><DD>
<DL COMPACT>
<DT id="13"><B>0</B>
<DD>
Success.
<DT id="14"><B>1</B>
<DD>
Various failures.
<DT id="15"><B>2</B>
<DD>
Forking the process to watch failed.
<DT id="16"><B>3</B>
<DD>
Replacing child process stdout with write side pipe failed.
<DT id="17"><B>4</B>
<DD>
Command execution failed.
<DT id="18"><B>5</B>
<DD>
Closing child process write pipe failed.
<DT id="19"><B>7</B>
<DD>
IPC pipe creation failed.
<DT id="20"><B>8</B>
<DD>
Getting child process return value with
<B><A HREF="/cgi-bin/man/man2html?2+waitpid">waitpid</A></B>(2)
failed, or command exited up on error.
<DT id="21"><B>other</B>
<DD>
The watch will propagate command exit status as child exit status.
</DL>
</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>NOTES</H2>
POSIX option processing is used (i.e., option processing stops at
the first non-option argument). This means that flags after
<I>command</I>
don't get interpreted by
<B>watch</B>
itself.
<A NAME="lbAH">&nbsp;</A>
<H2>BUGS</H2>
Upon terminal resize, the screen will not be correctly repainted until the
next scheduled update. All
<B>--differences</B>
highlighting is lost on that update as well.
<P>
Non-printing characters are stripped from program output. Use &quot;cat -v&quot; as
part of the command pipeline if you want to see them.
<P>
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.
<P>
Combining Characters never count as different in
<I>--differences</I>
mode. Only the base character counts.
<P>
Blank lines directly after a line which ends in the last column do not
display.
<P>
<I>--precise</I>
mode doesn't yet have advanced temporal distortion technology to compensate
for a
<I>command</I>
that takes more than
<I>interval</I>
seconds to execute.
<B>watch</B>
also can get into a state where it rapid-fires as many executions of
<I>command</I>
as it can to catch up from a previous executions running longer than
<I>interval</I>
(for example,
<B>netstat</B>
taking ages on a DNS lookup).
<A NAME="lbAI">&nbsp;</A>
<H2>EXAMPLES</H2>
<P>
To watch for mail, you might do
<DL COMPACT>
<DT id="22"><DD>
watch -n 60 from
</DL>
<P>
To watch the contents of a directory change, you could use
<DL COMPACT>
<DT id="23"><DD>
watch -d ls -l
</DL>
<P>
If you're only interested in files owned by user joe, you might use
<DL COMPACT>
<DT id="24"><DD>
watch -d 'ls -l | fgrep joe'
</DL>
<P>
To see the effects of quoting, try these out
<DL COMPACT>
<DT id="25"><DD>
watch echo $$
<BR>
watch echo '$$'
<BR>
watch echo &quot;'&quot;'$$'&quot;'&quot;
</DL>
<P>
To see the effect of precision time keeping, try adding
<I>-p</I>
to
<DL COMPACT>
<DT id="26"><DD>
watch -n 10 sleep 1
</DL>
<P>
You can watch for your administrator to install the latest kernel with
<DL COMPACT>
<DT id="27"><DD>
watch uname -r
</DL>
<P>
(Note that
<I>-p</I>
isn't guaranteed to work across reboots, especially in the face of
<B>ntpdate</B>
or other bootup time-changing mechanisms)
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="28"><A HREF="#lbAB">NAME</A><DD>
<DT id="29"><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT id="30"><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT id="31"><A HREF="#lbAE">OPTIONS</A><DD>
<DT id="32"><A HREF="#lbAF">EXIT STATUS</A><DD>
<DT id="33"><A HREF="#lbAG">NOTES</A><DD>
<DT id="34"><A HREF="#lbAH">BUGS</A><DD>
<DT id="35"><A HREF="#lbAI">EXAMPLES</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:29 GMT, March 31, 2021
</BODY>
</HTML>