watch(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

NAME

watch - Watch a file

SYNOPSIS

n watch
n watch-reset
watch-time

DESCRIPTION

watch monitors a file on the file system by periodically polling the file and reacquiring the contents into a buffer. The command is typically used to monitor build and logging files as their output changes under control of a background process. Any number of files may be watched simultaneously, however to minimize the number of file system transfers, only those buffers that are being viewed in a window are updated.

watch operates in three different modes:

Mode 1 (Reload)

On a re-fresh the existing buffer is emptied and the file contents are re-read in their entirety from the file system if the file has changed. This is the default mode of operation.

Mode 2 (Reload, Append)

On enabling the watch then the complete file is re-read, changes are subsequently read as deltas from the end of the file. This mode ensures that the buffer contents are up to date before incrementally reading the file.

Mode 3 (Append)

On enabling the watch then only the end of the file that has not been read before is appended to the end of the buffer. This method is ideal for large log files.

The operational mode may be selected by passing a numeric value of 1, 2 or 3 to the watch command. If no numeric argument is provided then the user is prompted for the operational mode.

Whilst running in an append mode (2 or 3) then byte offset of the end of the file is retained for the next read. On the next read then any new information from the last saved byte offset to the end of the file is read, irrespective of any edits made to the buffer. Therefore if the buffer contents have been deleted on the next append read then the buffer will contain the appended information only and not reacquire the information that has been deleted. Where the complete buffer is to be re-acquired then use Mode 1.

The buffer mode line is modified to show the watch state. i.e.

==W <buffer-name> ==============

Invocation of watch in a buffer that is being watched disables the watch. All watches may be removed from all buffers using 0 watch-reset.

watch-time modifies the poll time of a watch. The user is prompted for the time period which is entered in seconds.

watch-reset re-evaluates the watches that are on the buffers reporting the number of files that are bing watched. When invoked with a 0 argument then any outstanding watch commands are removed.

NOTES

watch is a macro implemented in watch.emf.

The commands watch-reset and watch-time are not available until a watch command has been executed.

HISTORY