← Back to branch summary

~ubuntu-branches/ubuntu/saucy/procps/saucy

« back to all changes in this revision

Viewing changes to watch.1

  • Committer: Package Import Robot
  • Author(s): Oliver Grawert
  • Date: 2012-06-20 13:12:40 UTC
  • mfrom: (2.1.21 sid)
  • Revision ID: package-import@ubuntu.com-20120620131240-923p0d8q88bmk3ac
Tags: 1:3.3.3-2ubuntu1
* Merge from Debian unstable.  Remaining changes:
  - debian/sysctl.d (Ubuntu-specific):
    + 10-console-messages.conf: stop low-level kernel messages on console.
    + 10-kernel-hardening.conf: add the kptr_restrict setting
    + 10-keyboard.conf.powerpc: mouse button emulation on PowerPC.
    + 10-network-security.conf: enable rp_filter and SYN-flood protection.
    + 10-ptrace.conf: describe new PTRACE setting.
    + 10-zeropage.conf: safe mmap_min_addr value for graceful fall-back.
    + README: describe how this directory is supposed to work.
  - debian/upstart (Ubuntu-specific): upstart configuration to replace old
    style sysv init script

Show diffs side-by-side

added added

removed removed

Lines of Context:
watch.1
1
 
.TH WATCH 1 "2010 Mar 01" " " "Linux User's Manual"
 
1
.TH WATCH "1" "June 2011" "procps-ng" "User Commands"
2
2
.SH NAME
3
3
watch \- execute a program periodically, showing output fullscreen
4
4
.SH SYNOPSIS
5
 
.na
6
5
.B watch
7
 
.RB [ \-bdehpvtx ]
8
 
.RB [ \-n
9
 
.IR seconds ]
10
 
.RB [ \-\-beep ]
11
 
.RB [ \-\-color ]
12
 
.RB [ \-\-differences[=\fIcumulative\fP]]
13
 
.RB [ \-\-errexit ]
14
 
.RB [ \-\-exec ]
15
 
.RB [ \-\-help ]
16
 
.RB [ \-\-interval=\fIseconds\fP]
17
 
.RB [ \-\-no\-title ]
18
 
.RB [ \-\-precise ]
19
 
.RB [ \-\-version ]
20
 
.I command
 
6
[\fIoptions\fR] \fIcommand\fR
21
7
.SH DESCRIPTION
22
8
.B watch
23
9
runs
24
10
.I command
25
11
repeatedly, displaying its output and errors (the first screenfull).  This
26
 
allows you to
27
 
watch the program output change over time.  By default, the program is run
28
 
every 2 seconds; use 
29
 
.B \-n
30
 
or
31
 
.B \-\-interval
32
 
to specify a different interval. Normally, this interval is interpreted
33
 
as the amout of time between the completion of one run of
34
 
.I command
35
 
and the beginning of the next run. However, with the
36
 
.I \-p
37
 
or
38
 
.I \-\-precise
39
 
option, you can make
 
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
40
30
.BR watch
41
31
attempt to run
42
32
.I command
44
34
.I interval
45
35
seconds. Try it with
46
36
.B ntptime
47
 
and notice how the fractional seconds stays
48
 
(nearly) the same, as opposed to normal mode where they continuously
49
 
increase.
50
 
.PP
51
 
The
52
 
.B \-d
53
 
or
54
 
.B \-\-differences
55
 
flag will highlight the differences between successive updates.  Using
56
 
.B \-\-differences=\fIcumulative\fP
57
 
makes highlighting "sticky", presenting a running display of all
58
 
positions that have ever changed.  The
59
 
.B \-t
60
 
or
61
 
.B \-\-no\-title
62
 
option turns off the header showing the interval, command, and current
63
 
time at the top of the display, as well as the following blank line.  The
64
 
.I \-b
65
 
or
66
 
.I \-\-beep
67
 
option causes the command to beep if it has a non-zero exit.
68
 
.PP
69
 
.B watch
70
 
will normally run until interrupted. If you want
71
 
.B watch
72
 
to exit on an error from the program running use the
73
 
.I \-e
74
 
or
75
 
.I \-\-errexit
76
 
options, which will cause
77
 
.B watch
78
 
to exit if the return value from the program is non-zero.
79
 
.PP
80
 
By default \fBwatch\fR will normally not pass escape characters, however
81
 
if you use the \fI\-\-c\fR or \fI\-\-color\fR option, then
82
 
\fBwatch\fR will interpret ANSI color sequences for the foreground.
83
 
 
 
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.
84
72
.SH NOTE
85
 
Note that
86
 
.I command
87
 
is given to "sh \-c"
88
 
which means that you may need to use extra quoting to get the desired effect.
89
 
You can disable this with the
90
 
.I -x
91
 
or
92
 
.I --exec
93
 
option, which passes the command to exec(2) instead.
94
 
.PP
95
73
Note that POSIX option processing is used (i.e., option processing stops at
96
74
the first non\-option argument).  This means that flags after
97
75
.I command
108
86
.IP
109
87
watch \-d ls \-l
110
88
.PP
111
 
If you're only interested in files owned by user joe, you might use 
 
89
If you're only interested in files owned by user joe, you might use
112
90
.IP
113
91
watch \-d 'ls \-l | fgrep joe'
114
92
.PP
150
128
.PP
151
129
Combining Characters never count as different in
152
130
.I \-\-differences
153
 
mode. Only the base character counts.
 
131
mode.  Only the base character counts.
154
132
.PP
155
133
Blank lines directly after a line which ends in the last column do not
156
134
display.
157
135
.PP
158
136
.I \-\-precise
159
 
mode doesn't yet have advanced temporal distortion technology to
160
 
compensate for a
 
137
mode doesn't yet have advanced temporal distortion technology to compensate
 
138
for a
161
139
.I command
162
140
that takes more than
163
141
.I interval
170
148
(for example,
171
149
.B netstat
172
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.
173
184
.SH AUTHORS
174
185
The original
175
186
.B watch
176
 
was written by Tony Rems <rembo@unisoft.com> in 1991, with mods and
 
187
was written by
 
188
.UR rembo@\:unisoft.\:com
 
189
Tony Rems
 
190
.UE
 
191
in 1991, with mods and
177
192
corrections by Francois Pinard.  It was reworked and new features added by
178
 
Mike Coleman <mkc@acm.org> in 1999.  The beep, exec, and error handling
179
 
features were added by Morty Abzug <morty@frakir.org> in 2008.
180
 
On a not so dark and stormy morning
181
 
in March of 2003, Anthony DeRobertis <asd@suespammers.org> got sick of
182
 
his watches that should update every minute eventually updating many
183
 
seconds after the minute started, and added microsecond precision.
184
 
Unicode support was added in 2009 by Jarrod Lowe <procps@rrod.net>.
 
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