diff options
author | Craig Small <csmall@dropbear.xyz> | 2022-08-29 18:07:43 +1000 |
---|---|---|
committer | Craig Small <csmall@dropbear.xyz> | 2022-08-29 18:07:43 +1000 |
commit | 8e889ae68214241232ad522c359236ee68417733 (patch) | |
tree | 39943fd2fbfbe8d6805184cb159d80c6e18d9408 /man/watch.1 | |
parent | 5fcf104cba0eada8aca1f871195675f1287b5a80 (diff) | |
download | procps-ng-8e889ae68214241232ad522c359236ee68417733.tar.gz |
build-sys: Rearrange the manual pages
All man pages are found in ./man
man-po -> po-man
References:
https://www.freelists.org/post/procps/Next-for-newlib,3
Signed-off-by: Craig Small <csmall@dropbear.xyz>
Diffstat (limited to 'man/watch.1')
-rw-r--r-- | man/watch.1 | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/man/watch.1 b/man/watch.1 new file mode 100644 index 0000000..cef2cab --- /dev/null +++ b/man/watch.1 @@ -0,0 +1,203 @@ +.TH WATCH 1 "2021-04-24" "procps-ng" "User Commands" +.SH NAME +watch \- execute a program periodically, showing output fullscreen +.SH SYNOPSIS +.B watch +[\fIoptions\fR] \fIcommand\fR +.SH DESCRIPTION +.B watch +runs +.I command +repeatedly, displaying its output and errors (the first screenfull). This +allows you to watch the program output change over time. By default, +\fIcommand\fR is run every 2 seconds and \fBwatch\fR will run until interrupted. +.SH OPTIONS +.TP +\fB\-d\fR, \fB\-\-differences\fR[=\fIpermanent\fR] +Highlight the differences between successive updates. If the optional +\fIpermanent\fR argument is specified then +.B watch +will show all changes since the first iteration. +.TP +\fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR +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. The WATCH_INTERVAL environment can be used to persistently +set a non-default interval (following the same rules and formatting). +.TP +\fB\-p\fR, \fB\-\-precise\fR +Make +.BR watch +attempt to run +.I command +every +.B \-\-interval +.IR seconds . +Try it with +.B ntptime +(if present) and notice how the fractional seconds stays (nearly) the same, as opposed to +normal mode where they continuously increase. +.TP +\fB\-t\fR, \fB\-\-no\-title\fR +Turn off the header showing the interval, command, and current time at the +top of the display, as well as the following blank line. +.TP +\fB\-b\fR, \fB\-\-beep\fR +Beep if command has a non-zero exit. +.TP +\fB\-e\fR, \fB\-\-errexit\fR +Freeze updates on command error, and exit after a key press. +.TP +\fB\-g\fR, \fB\-\-chgexit\fR +Exit when the output of +.I command +changes. +.TP +\fB\-q\fR, \fB\-\-equexit\fR <cycles> +Exit when output of +.I command +does not change for the given number of cycles. +.TP +\fB\-c\fR, \fB\-\-color\fR +Interpret ANSI color and style sequences. +.TP +\fB\-x\fR, \fB\-\-exec\fR +Pass +.I command +to +.BR exec (2) +instead of +.B sh \-c +which reduces the need to use extra quoting to get the desired effect. +.TP +\fB\-w\fR, \fB\-\-no\-wrap\fR +Turn off line wrapping. Long lines will be truncated instead of wrapped to the next line. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.TP +\fB\-v\fR, \fB\-\-version\fR +Display version information and exit. +.SH "EXIT STATUS" +.PP +.RS +.PD 0 +.TP +.B 0 +Success. +.TP +.B 1 +Various failures. +.TP +.B 2 +Forking the process to watch failed. +.TP +.B 3 +Replacing child process stdout with write side pipe failed. +.TP +.B 4 +Command execution failed. +.TP +.B 5 +Closing child process write pipe failed. +.TP +.B 7 +IPC pipe creation failed. +.TP +.B 8 +Getting child process return value with +.BR waitpid (2) +failed, or command exited up on error. +.TP +.B other +The watch will propagate command exit status as child exit status. +.SH ENVIRONMENT +The behaviour of +.B watch +is affected by the following environment variables. + +.TP +.B WATCH_INTERVAL +Update interval, follows the same rules as the +.B \-\-interval +command line option. +.SH NOTES +POSIX option processing is used (i.e., option processing stops at +the first non\-option argument). This means that flags after +.I command +don't get interpreted by +.BR watch +itself. +.SH BUGS +Upon terminal resize, the screen will not be correctly repainted until the +next scheduled update. All +.B \-\-differences +highlighting is lost on that update as well. + +Non-printing characters are stripped from program output. Use \fBcat -v\fR as +part of the command pipeline if you want to see them. + +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. + +Combining Characters never count as different in +.B \-\-differences +mode. Only the base character counts. + +Blank lines directly after a line which ends in the last column do not +display. + +.B \-\-precise +mode doesn't yet have advanced temporal distortion technology to compensate +for a +.I command +that takes more than +.B \-\-interval +.I seconds +to execute. +.B watch +also can get into a state where it rapid-fires as many executions of +.I command +as it can to catch up from a previous executions running longer than +.B \-\-interval +(for example, +.B netstat +taking ages on a DNS lookup). +.SH EXAMPLES +.PP +To watch for mail, you might do +.IP +watch \-n 60 from +.PP +To watch the contents of a directory change, you could use +.IP +watch \-d ls \-l +.PP +If you're only interested in files owned by user joe, you might use +.IP +watch \-d 'ls \-l | fgrep joe' +.PP +To see the effects of quoting, try these out +.IP +watch echo $$ +.br +watch echo '$$' +.br +watch echo "'"'$$'"'" +.PP +To see the effect of precision time keeping, try adding +.B \-p +to +.IP +watch \-n 10 sleep 1 +.PP +You can watch for your administrator to install the latest kernel with +.IP +watch uname \-r +.PP +(Note that +.B \-p +isn't guaranteed to work across reboots, especially in the face of +.B ntpdate +(if present) or other bootup time-changing mechanisms) |