watch.1

   1 .TH WATCH "1" "June 2011" "procps-ng" "User Commands"
   2 .SH NAME
   3 watch \- execute a program periodically, showing output fullscreen
   4 .SH SYNOPSIS
   5 .B watch
   6 [\fIoptions\fR] \fIcommand\fR
   7 .SH DESCRIPTION
   8 .B watch
   9 runs
  10 .I command
  11 repeatedly, displaying its output and errors (the first screenfull).  This
  12 allows you to watch the program output change over time.  By default, the
  13 program is run every 2 seconds.
  14 By default,
  15 .B watch
  16 will run until interrupted.
  17 .SH OPTIONS
  18 .TP
  19 \fB\-d\fR, \fB\-\-differences\fR [\fIpermanent\fR]
  20 Highlight the differences between successive updates.  Option will read
  21 optional argument that changes highlight to be permanent, allowing to see what
  22 has changed at least once since first iteration.
  23 .TP
  24 \fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR
  25 Specify update interval.  The command will not allow quicker than 0.1 second
  26 interval, in which the smaller values are converted.
  27 .TP
  28 \fB\-p\fR, \fB\-\-precise\fR
  29 Make
  30 .BR watch
  31 attempt to run
  32 .I command
  33 every
  34 .I interval
  35 seconds. Try it with
  36 .B ntptime
  37 and notice how the fractional seconds stays (nearly) the same, as opposed to
  38 normal mode where they continuously increase.
  39 .TP
  40 \fB\-t\fR, \fB\-\-no\-title\fR
  41 Turn off the header showing the interval, command, and current time at the
  42 top of the display, as well as the following blank line.
  43 .TP
  44 \fB\-b\fR, \fB\-\-beep\fR
  45 Beep if command has a non-zero exit.
  46 .TP
  47 \fB\-e\fR, \fB\-\-errexit\fR
  48 Freeze updates on command error, and exit after a key press.
  49 .TP
  50 \fB\-g\fR, \fB\-\-chgexit\fR
  51 Exit when the output of
  52 .I command
  53 changes.
  54 .TP
  55 \fB\-c\fR, \fB\-\-color\fR
  56 Interpret ANSI color sequences.
  57 .TP
  58 \fB\-x\fR, \fB\-\-exec\fR
  59 .I command
  60 is given to
  61 .B sh \-c
  62 which means that you may need to use extra quoting to get the desired effect.
  63 This with the \-\-exec option, which passes the command to
  64 .BR exec (2)
  65 instead.
  66 .TP
  67 \fB\-h\fR, \fB\-\-help\fR
  68 Display help text and exit.
  69 .TP
  70 \fB\-v\fR, \fB\-\-version\fR
  71 Display version information and exit.
  72 .SH NOTE
  73 Note that POSIX option processing is used (i.e., option processing stops at
  74 the first non\-option argument).  This means that flags after
  75 .I command
  76 don't get interpreted by
  77 .BR watch
  78 itself.
  79 .SH EXAMPLES
  80 .PP
  81 To watch for mail, you might do
  82 .IP
  83 watch \-n 60 from
  84 .PP
  85 To watch the contents of a directory change, you could use
  86 .IP
  87 watch \-d ls \-l
  88 .PP
  89 If you're only interested in files owned by user joe, you might use
  90 .IP
  91 watch \-d 'ls \-l | fgrep joe'
  92 .PP
  93 To see the effects of quoting, try these out
  94 .IP
  95 watch echo $$
  96 .br
  97 watch echo '$$'
  98 .br
  99 watch echo "'"'$$'"'"
 100 .PP
 101 To see the effect of precision time keeping, try adding
 102 .I \-p
 103 to
 104 .IP
 105 watch \-n 10 sleep 1
 106 .PP
 107 You can watch for your administrator to install the latest kernel with
 108 .IP
 109 watch uname \-r
 110 .PP
 111 (Note that
 112 .I \-p
 113 isn't guaranteed to work across reboots, especially in the face of
 114 .B ntpdate
 115 or other bootup time-changing mechanisms)
 116 .SH BUGS
 117 Upon terminal resize, the screen will not be correctly repainted until the
 118 next scheduled update.  All
 119 .B \-\-differences
 120 highlighting is lost on that update as well.
 121 .PP
 122 Non-printing characters are stripped from program output.  Use "cat -v" as
 123 part of the command pipeline if you want to see them.
 124 .PP
 125 Combining Characters that are supposed to display on the character at the
 126 last column on the screen may display one column early, or they may not
 127 display at all.
 128 .PP
 129 Combining Characters never count as different in
 130 .I \-\-differences
 131 mode.  Only the base character counts.
 132 .PP
 133 Blank lines directly after a line which ends in the last column do not
 134 display.
 135 .PP
 136 .I \-\-precise
 137 mode doesn't yet have advanced temporal distortion technology to compensate
 138 for a
 139 .I command
 140 that takes more than
 141 .I interval
 142 seconds to execute.
 143 .B watch
 144 also can get into a state where it rapid-fires as many executions of
 145 .I command
 146 as it can to catch up from a previous executions running longer than
 147 .I interval
 148 (for example,
 149 .B netstat
 150 taking ages on a DNS lookup).
 151 .SH "EXIT STATUS"
 152 .PP
 153 .RS
 154 .PD 0
 155 .TP
 156 .B 0
 157 Success.
 158 .TP
 159 .B 1
 160 Various failures.
 161 .TP
 162 .B 2
 163 Forking the process to watch failed.
 164 .TP
 165 .B 3
 166 Replacing child process stdout with write side pipe failed.
 167 .TP
 168 .B 4
 169 Command execution failed.
 170 .TP
 171 .B 5
 172 Closign child process write pipe failed.
 173 .TP
 174 .B 7
 175 IPC pipe creation failed.
 176 .TP
 177 .B 8
 178 Getting child process return value with
 179 .BR waitpid (2)
 180 failed, or command exited up on error.
 181 .TP
 182 .B other
 183 The watch will propagate command exit status as child exit status.
 184 .SH AUTHORS
 185 The original
 186 .B watch
 187 was written by
 188 .UR rembo@\:unisoft.\:com
 189 Tony Rems
 190 .UE
 191 in 1991, with mods and
 192 corrections by Francois Pinard.  It was reworked and new features added by
 193 .UR mkc@\:acm.\:org
 194 Mike Coleman
 195 .UE
 196 in 1999. The beep, exec, and error handling features were added by
 197 .UR morty@\:frakir.\:org
 198 Morty Abzug
 199 .UE
 200 in 2008.  On a not so dark and stormy morning in March of 2003,
 201 .UR asd@\:suespammers.\:org
 202 Anthony DeRobertis
 203 .UE
 204 got sick of his watches that should update every minute eventually updating
 205 many seconds after the minute started, and added microsecond precision.
 206 Unicode support was added in 2009 by
 207 .UR procps@\:rrod.\:net
 208 Jarrod Lowe
 209 .UE