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, command is run every 2 seconds and watch will
15 run until interrupted.
16
18 -b, --beep
19 Beep if command has a non-zero exit.
20 -c, --color
22 Interpret ANSI color and style sequences.
23 -d, --differences[=permanent]
25 Highlight the differences between successive updates. If the op‐
26 tional permanent argument is specified then watch will show all
27 changes since the first iteration.
28 -e, --errexit
30 Freeze updates on command error, and exit after a key press.
31 -g, --chgexit
33 Exit when the output of command changes.
34 -n, --interval seconds
36 Specify update interval. The command will not allow quicker
37 than 0.1 second interval, in which the smaller values are con‐
38 verted. Both '.' and ',' work for any locales. The WATCH_INTER‐
39 VAL environment can be used to persistently set a non-default
40 interval (following the same rules and formatting).
41 -p, --precise
43 Make watch attempt to run command every --interval seconds. Try
44 it with ntptime (if present) and notice how the fractional sec‐
45 onds stays (nearly) the same, as opposed to normal mode where
46 they continuously increase.
47 -q, --equexit <cycles>
49 Exit when output of command does not change for the given number
50 of cycles.
51 -r, --no-rerun
53 Do not run the program on terminal resize, the output of the
54 program will re-appear at the next regular run time.
55 -t, --no-title
57 Turn off the header showing the interval, command, and current
58 time at the top of the display, as well as the following blank
59 line.
60 -w, --no-wrap
62 Turn off line wrapping. Long lines will be truncated instead of
63 wrapped to the next line.
64 -x, --exec
66 Pass command to exec(2) instead of sh -c which reduces the need
67 to use extra quoting to get the desired effect.
68 -h, --help
70 Display help text and exit.
71 -v, --version
73 Display version information and exit.
74
76 0 Success.
77 1 Various failures.
78 2 Forking the process to watch failed.
79 3 Replacing child process stdout with write side pipe
80 failed.
81 4 Command execution failed.
82 5 Closing child process write pipe failed.
83 7 IPC pipe creation failed.
84 8 Getting child process return value with waitpid(2)
85 failed, or command exited up on error.
86 other The watch will propagate command exit status as child
87 exit status.
89 The behavior of watch is affected by the following environment vari‐
90 ables.
91 WATCH_INTERVAL
93 Update interval, follows the same rules as the --interval com‐
94 mand line option.
95
97 POSIX option processing is used (i.e., option processing stops at the
98 first non-option argument). This means that flags after command don't
99 get interpreted by watch itself.
100
102 Upon terminal resize, the screen will not be correctly repainted until
103 the next scheduled update. All --differences highlighting is lost on
104 that update as well. When using the --no-rerun option, no output of
105 will be visible.
106 Non-printing characters are stripped from program output. Use cat -v
108 as part of the command pipeline if you want to see them.
109 Combining Characters that are supposed to display on the character at
111 the last column on the screen may display one column early, or they may
112 not display at all.
113 Combining Characters never count as different in --differences mode.
115 Only the base character counts.
116 Blank lines directly after a line which ends in the last column do not
118 display.
119 --precise mode doesn't yet have advanced temporal distortion technology
121 to compensate for a command that takes more than --interval seconds to
122 execute. watch also can get into a state where it rapid-fires as many
123 executions of command as it can to catch up from a previous executions
124 running longer than --interval (for example, netstat(8) taking ages on
125 a DNS lookup).
126
128 To watch for mail, you might do
129 watch -n 60 from
130 To watch the contents of a directory change, you could use
131 watch -d ls -l
132 If you're only interested in files owned by user joe, you might use
133 watch -d 'ls -l | fgrep joe'
134 To see the effects of quoting, try these out
135 watch echo $$
136 watch echo '$$'
137 watch echo "'"'$$'"'"
138 To see the effect of precision time keeping, try adding -p to
139 watch -n 10 sleep 1
140 You can watch for your administrator to install the latest kernel with
141 watch uname -r
142 (Note that -p isn't guaranteed to work across reboots, especially in
143 the face of ntpdate (if present) or other bootup time-changing mecha‐
144 nisms)
145
147 Please send bug reports to ⟨procps@freelists.org⟩
148procps-ng 2023-01-17 WATCH(1)