1WATCH(1) User Commands WATCH(1)
2
6 watch - execute a program periodically, showing output fullscreen
7
9 watch [options] command
10
12 watch runs command repeatedly, displaying its output and errors (the
13 first screenfull). This allows you to watch the program output change
14 over time. By default, the program is run every 2 seconds. By
15 default, watch will run until interrupted.
16
18 -d, --differences [permanent]
19 Highlight the differences between successive updates. Option
20 will read optional argument that changes highlight to be perma‐
21 nent, allowing to see what has changed at least once since first
22 iteration.
23 -n, --interval seconds
25 Specify update interval. The command will not allow quicker
26 than 0.1 second interval, in which the smaller values are con‐
27 verted.
28 -p, --precise
30 Make watch attempt to run command every interval seconds. Try it
31 with ntptime and notice how the fractional seconds stays
32 (nearly) the same, as opposed to normal mode where they continu‐
33 ously increase.
34 -t, --no-title
36 Turn off the header showing the interval, command, and current
37 time at the top of the display, as well as the following blank
38 line.
39 -b, --beep
41 Beep if command has a non-zero exit.
42 -e, --errexit
44 Freeze updates on command error, and exit after a key press.
45 -g, --chgexit
47 Exit when the output of command changes.
48 -c, --color
50 Interpret ANSI color and style sequences.
51 -x, --exec
53 command is given to sh -c which means that you may need to use
54 extra quoting to get the desired effect. This with the --exec
55 option, which passes the command to exec(2) instead.
56 -h, --help
58 Display help text and exit.
59 -v, --version
61 Display version information and exit.
62
64 Note that POSIX option processing is used (i.e., option processing
65 stops at the first non-option argument). This means that flags after
66 command don't get interpreted by watch itself.
67
69 To watch for mail, you might do
70 watch -n 60 from
72 To watch the contents of a directory change, you could use
74 watch -d ls -l
76 If you're only interested in files owned by user joe, you might use
78 watch -d 'ls -l | fgrep joe'
80 To see the effects of quoting, try these out
82 watch echo $$
84 watch echo '$$'
85 watch echo "'"'$$'"'"
86 To see the effect of precision time keeping, try adding -p to
88 watch -n 10 sleep 1
90 You can watch for your administrator to install the latest kernel with
92 watch uname -r
94 (Note that -p isn't guaranteed to work across reboots, especially in
96 the face of ntpdate or other bootup time-changing mechanisms)
97
99 Upon terminal resize, the screen will not be correctly repainted until
100 the next scheduled update. All --differences highlighting is lost on
101 that update as well.
102 Non-printing characters are stripped from program output. Use "cat -v"
104 as part of the command pipeline if you want to see them.
105 Combining Characters that are supposed to display on the character at
107 the last column on the screen may display one column early, or they may
108 not display at all.
109 Combining Characters never count as different in --differences mode.
111 Only the base character counts.
112 Blank lines directly after a line which ends in the last column do not
114 display.
115 --precise mode doesn't yet have advanced temporal distortion technology
117 to compensate for a command that takes more than interval seconds to
118 execute. watch also can get into a state where it rapid-fires as many
119 executions of command as it can to catch up from a previous executions
120 running longer than interval (for example, netstat taking ages on a DNS
121 lookup).
122
124 0 Success.
125 1 Various failures.
126 2 Forking the process to watch failed.
127 3 Replacing child process stdout with write side pipe
128 failed.
129 4 Command execution failed.
130 5 Closing child process write pipe failed.
131 7 IPC pipe creation failed.
132 8 Getting child process return value with waitpid(2)
133 failed, or command exited up on error.
134 other The watch will propagate command exit status as child
135 exit status.
137 The original watch was written by Tony Rems ⟨rembo@unisoft.com⟩ in
138 1991, with mods and corrections by Francois Pinard. It was reworked
139 and new features added by Mike Coleman ⟨mkc@acm.org⟩ in 1999. The beep,
140 exec, and error handling features were added by Morty Abzug ⟨morty@
141 frakir.org⟩ in 2008. On a not so dark and stormy morning in March of
142 2003, Anthony DeRobertis ⟨asd@suespammers.org⟩ got sick of his watches
143 that should update every minute eventually updating many seconds after
144 the minute started, and added microsecond precision. Unicode support
145 was added in 2009 by Jarrod Lowe ⟨procps@rrod.net⟩
146procps-ng June 2011 WATCH(1)