XWatch <br> The Logfiles Watcher

- Next chapter
- Previous chapter
- Table of contents

# Chapter 2: Using xwatch

You typically start `xwatch` when activating an X session; e.g., from the file which xdm uses to fire up a user's session (this file is normally `/usr/X11/lib/X11/xdm/Xsession`). The command that starts `xwatch` is something like

    xwatch [options] files &

where `options' are optional flags, files are the files to watch, and the ampersand character is used to start `xwatch` in the background. The files to watch are typically in the directory `/var/adm/`: files which are created by the syslog daemon (see the file `syslogd.conf.SAMPLE` in the distribution for an example). `XWatch` accepts only filenames which are:

- ordinary files, no sockets, directory names,

- which are not binary files.

Other files as stated on the commandline are not monitored. When any `non-proper' file is given on the commandline, `xwatch` warns about the file not being acceptable and deletes it from its list of names.

## 2.1: Options to the xwatch program

The options are many, start `xwatch` without arguments to see what is supported. All options can also be stated in the file `/usr/lib/X11/app-defaults/XWatch` as X resources (see the file `XWatch.ap` as an example). In the following enumeration, a nr denotes a number:

- `-border` nr: Specifies whether `xwatch` should start with a border. The nr must be 0 or 1. When you start `xwatch` without a border, your window manager may not be able to resize or even recognize it. Incidentally, this may be what you want -- I use it to `hide' the presence of `xwatch` from my window manager `fvwm`.

- `-geometry` geom: Specifies the display geometry, á-la other X programs. You can express the geometry in terms of WxH (width by height), optionally postfixed by +X+Y (x and y offset) or -X-Y (offsets relative to the lower right corner) and other combinations.

  Note that previous switches that emulated the geometry specification, such as `-xpos` and `-height`, are now obsolete. Use the geometry setting.

- `-fg` color and `-bg` color: These options define the default foreground and background of the watch window.

  Note that previous switches, such as `-bred` and `-bblue`, are now obsolete.

- `-printtime` nr: Defines whether `xwatch` should prefix any info on the watched files with a timestamp. The `nr` can be 0 or zero; the timestamp is printed when nr is 1.

- `-printname` nr: Defines whether `xwatch` should prefix any info on the watched files with the filename. The nr is again a flag, 0 or 1.

- `-newline` nr: Defines whether `xwatch` should let a newline follow the time and/or filename stamp, so that the actual information is displayed on its own line.

- `-interval` nr: Defines the scanning interval. Each nr seconds, `xwatch` will check if new information has arrived on the watched files. The nr may be between 1 and 30 seconds.

- `-fontsize` nr: Defines the initial size of the display font. The nr may range from 1 to 4; 1 being the smallest font and 4 being the largest.

- `-fontstyle` nr: Defines the style of the used font. The nr is a number between 0 and 15 (0 being the default). Start `xwatch` without arguments or read the application defaults file to see what fonts the numbers choose.

- `-firstwarnings` nr: Defines whether `xwatch` should print initial warnings into the watch window. E.g., you might like to set `firstwarnings` to zero, and then start `xwatch` with the file argument `/var/adm/*`. Warnings about, e.g., `utmp` being a binary file would then be suppressed.

- `-printversion` nr: Controls whether `xwatch` prints its version number and copyright notice upon startup in the watch window.

- `-gag` text: This option, when present, prevents all lines with text in them from being shown in the display window. You can specify more than one string to `gag', in that case, separate the strings with `|`.

- `-colorstring` col:string: This option causes lines that contain `string` to be displayed using the specified color. The string is matched literally. E.g., if you use the option `-colorstring blue:connection` then all lines containing `connection` are displayed in pure blue.

  You can specify several colorstrings by separating all options with a | character, as in `-colorstring blue:connection|red:error`. Note that, for reasons of shell expansion, you should quote such options on the commandline.

- `-title` name: This option sets the window title of the watch window. Note that the title will only be visible when `border` is not 0. This option may be useful if you have several XWatch windows, monitoring different things.

- `-ignore` fileA|fileB|fileC|...: This option is handy if you start XWatch with a wildcard file argument, but when you want XWatch not to process some files. The `-ignore` flag removes the stated files from the watchlist. Note that, for reasons of shell commandline expansion, you must quote the file specification (or the shell will interpret the | characters as pipes). (Thanks, Frank Brokken, `frank@icce.rug.nl` for the code).

Before you extensively use the options, create an application defaults file `/usr/lib/X11/app-defaults/XWatch`. You can do so by copying the file `XWatch.ap`, extracted from the archive, to `/usr/lib/X11/app-defaults/XWatch`. The comments in the distributed application defaults file explain what you can configure and show examples.

Some systems do not have the directory `/usr/lib/X11/app-defaults`. In that case, you should create the following links:

- `/usr/X11` should point to your X11 distribution; e.g. to `/usr/X11R6`. That way, you always have e.g. `/usr/X11/bin`, even after upgrading your X11 distribution. All that is needed is one new link.

- `/usr/lib/X11` should point to `/usr/X11/lib/X11`.

Then edit the file `XWatch` in the application defaults directory, and follow the instructions therein to define your favorite settings. If you need to start `xwatch` incidentally with another setting, use a flag.

## 2.2: File arguments

The filename arguments can optionally be followed by a color specification that applies only to that particular file. E.g., say you want to see all the files in `/var/adm` normally in blue text; but you want to see `/var/adm/critical` (critical messages from applications) in yellow and `/var/adm/auth` (authentification messages) in red. In that case, the course to follow would be:

- The default foreground color would be blue. You could set this with the flags `-fg blue`, or in the application defaults file.

- The color for `/var/adm/critical` should be yellow. Hence, the first file argument would be `/var/adm/critical:yellow`.

- The color for file `/var/adm/auth` should be red, hence the second file argument would be `/var/adm/auth:red`.

- The following arguments would be the files, using the standard foreground (blue): `/var/adm/*`, without any extra color specifications.

Such a commandline would cause `xwatch` to complain about the multiple presence of `/var/adm/critical` (once from the separate argument, and once from the wildcard argument) and similarly about `/var/adm/auth`. If this bothers you, turn off the initial warnings (e.g., using `-firstwarnings 0` or in the application defaults file).

Note that besides the color specifications for filenames, you can also specify coloring for lines that match a given string in all files. See the above description of the switch `-colorstring` for more information.

- Next chapter
- Previous chapter
- Table of contents