.TH "XWatch 
.br 
The Logfiles Watcher" "1996"
.PP
.SH "XWatch 
.br 
The Logfiles Watcher"
.SH "Karel Kubat (karel@icce\&.rug\&.nl) 
.br 
State University of Groningen 
.br 
Westerhaven 16, 9718 AW Groningen 
.br 
The Netherlands"
.SH "1996"

.PP 

.SH "Chapter 1: Introduction"

.PP 
XWatch is a small program that I wrote to monitor logfiles and to see
any changes \fBdirectly\fP (instead of having to read all the logs after a
breakin or a crash)\&. XWatch is simply started with a few file
arguments, and any information that appears on the files is displayed\&.
With a slider you can see past information; i\&.e\&., lines that scroll in
xwatch\(cq\&s window\&. That\(cq\&s all there is to it\&. The appearance of the
xwatch window can furthermore be modified via command line flags or
via an application defaults file\&. (Older versions of XWatch had a
button to activate an `options\(cq\& window\&. I removed this code, almost no\-one
uses it\&.)
.PP 
XWatch is incidentally my first applications with the XForms GUI
library for X, which I can highly recommend for developers who want to
start `X programming\(cq\& but who don\(cq\&t want to go through the hassle of
having to learn about intrinsics\&. XForms is really excellent\&. Congrats,
T\&.C\&. Zhao and Mark Overmars (the latter is rumored to bootleg at a soccer
club in his free time ;)\&. Instructions on where and how to get the XForms
library are in the Makefile, contained in xwatch\(cq\&s distribution\&.
.PP 
\fBDebian maintainer note:\fP XWatch doesn\(cq\&t have an active upstream
maintainer\&.  If you are interested in taking over this package, please see
the file /usr/share/doc/xwatch/README\&.debian
.PP 

.SH "Chapter 2: Using xwatch"

.PP 
You typically start xwatch when activating an X session; e\&.g\&.,
from the file which xdm uses to fire up a user\(cq\&s session (this file is
normally /usr/X11/lib/X11/xdm/Xsession)\&. The command that starts
xwatch is something like
.PP 
.nf 
xwatch [options] files &

.fi 

.PP 
where `options\(cq\& 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:
.PP 
startit()
.PP 
.IP o 
ordinary files, no sockets, directory names,
.PP 
.IP o 
which are not binary files\&.
.PP 
endit() 
.PP 
Other files as stated on the commandline are not monitored\&. When any
`non\-proper\(cq\& file is given on the commandline, xwatch warns about the
file not being acceptable and deletes it from its list of names\&.
.PP 

.SH "2\&.1: Options to the xwatch program"

.PP 
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 \fInr\fP
denotes a number:
.PP 
startit()
.PP 
.IP o 
\-border \fInr\fP:  Specifies whether xwatch should start
with a border\&. The \fInr\fP 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\(cq\& the presence of xwatch from my window manager fvwm\&. 
.PP 
.IP o 
\-geometry \fIgeom\fP: Specifies the display geometry, a\-la 
other X programs\&. You can express the geometry in terms of \fIWxH\fP 
(width by height), optionally postfixed by \fI+X+Y\fP (x and y offset) 
or \fI\-X\-Y\fP (offsets relative to the lower right corner) and other 
combinations\&. 
.PP 
Note that previous switches that emulated the geometry specification, 
such as \-xpos and \-height, are now obsolete\&. Use the geometry 
setting\&.
.PP 
.IP o 
\-fg \fIcolor\fP and \-bg \fIcolor\fP: These options define the 
default foreground and background of the watch window\&.
.PP 
Note that previous switches, such as \-bred and \-bblue, are now 
obsolete\&. 
.PP 
.IP o 
\-printtime \fInr\fP: 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 \fInr\fP is 1\&.
.PP 
.IP o 
\-printname \fInr\fP: Defines whether xwatch should prefix
any info on the watched files with the filename\&. The \fInr\fP is again a
flag, 0 or 1\&.
.PP 
.IP o 
\-newline \fInr\fP: 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\&.
.PP 
.IP o 
\-interval \fInr\fP: Defines the scanning interval\&.  Each \fInr\fP
seconds, xwatch will check if new information has arrived on the
watched files\&. The \fInr\fP may be between 1 and 30 seconds\&. 
.PP 
.IP o 
\-fontsize \fInr\fP: Defines the initial size of the display
font\&.  The \fInr\fP may range from 1 to 4; 1 being the smallest font and
4 being the largest\&.
.PP 
.IP o 
\-fontstyle \fInr\fP: Defines the style of the used font\&. The
\fInr\fP 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\&.
.PP 
.IP o 
\-firstwarnings \fInr\fP: 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\&.
.PP 
.IP o 
\-printversion \fInr\fP: Controls whether xwatch prints its
version number and copyright notice upon startup in the watch window\&.
.PP 
.IP o 
\-gag \fItext\fP: This option, when present, prevents all lines 
with \fItext\fP in them from being shown in the display window\&. You can 
specify more than one string to `gag\(cq\&, in that case, separate the 
strings with |\&.
.PP 
.IP o 
\-colorstring \fIcol:string\fP: 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\&.
.PP 
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\&.
.PP 
.IP o 
\-title \fIname\fP: 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\&.
.PP 
.IP o 
\-ignore \fIfileA|fileB|fileC|\&.\&.\&.\fP: This option is handy if 
you start XWatch with a wildcard file argument, but when you want 
XWatch \fBnot\fP 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)\&.
.PP 
endit()
.PP 
\fBDebian Maintainer\(cq\&s note: Applications defaults are stored in
/etc/X11/app\-defaults/XWatch \&.  System adminitrators who want to
customize xwatch globally may also create a file
/etc/X11/Xresources/xwatch for these configurations by prefixing
the entries with Xwatch  (see /usr/share/doc/xwatch/README\&.Debian
for an example)\&.  Individual users can make the same types of
changes in their ~/\&.Xdefaults or ~/\&.Xresources files\&.\fP
.PP 
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\&. 
.PP 
Some systems do not have the directory /usr/lib/X11/app\-defaults\&.  In
that case, you should create the following links:
.PP 
startit()
.PP 
.IP o 
/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\&.
.PP 
.IP o 
/usr/lib/X11 should point to /usr/X11/lib/X11\&.
.PP 
endit()
.PP 
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\&.
.PP 

.SH "2\&.2: File arguments"

.PP 
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:
.PP 
startit()
.PP 
.IP o 
The default foreground color would be blue\&. You could set this
with the flags \-fg blue, or in the application
defaults file\&.
.PP 
.IP o 
The color for /var/adm/critical should be yellow\&.  Hence, the
first file argument would be /var/adm/critical:yellow\&.
.PP 
.IP o 
The color for file /var/adm/auth should be red, hence the
second file argument would be /var/adm/auth:red\&.
.PP 
.IP o 
The following arguments would be the files, using the standard
foreground (blue): /var/adm/*, without any extra color
specifications\&.
.PP 
endit() 
.PP 
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)\&.
.PP 
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\&.
.PP 

.SH "Chapter 3: Obtaining xwatch"

.PP 
XWatch can be obtained at the ftp site ftp\&.icce\&.rug\&.nl, in the directory /pub/unix, as the file xwatch\-X\&.YY\&.tar\&.gz\&.
X\&.YY is the version number, e\&.g\&., 1\&.00\&. This site is the primary site,
so check here for new versions\&.
.PP 
To unpack the archive, change\-dir to your `sources\(cq\& directory (e\&.g\&.,
/usr/local/src) and type
.PP 
.nf 
tar xvzf /where/ever/you/put/it/xwatch\-X\&.YY\&.tar\&.gz

.fi 

.PP 
Next, change\-dir to the unpacked subdirectory xwatch and check there\&.
You will find a subdirectory src with the full sources\&.
.PP 

.SH "Chapter 4: Compiling xwatch"

.PP 
Follow these steps\&.
.PP 
startit()
.PP 
.IP o 
You will need the XForms library and include files to compile
xwatch\&.  Check the Makefile in the src subdirectory for
two ftp sites that carry XForms for Linux\&. Obtain the library and
install it\&.  XWatch will happily run with XForms version 0\&.81 or 0\&.88\&.
.PP 
.IP o 
In the src subdirectory, edit the Makefile and adjust
some defines at the top\&. E\&.g\&., a make install copies the binary by
default to /usr/local/X11/bin; adjust that if you don\(cq\&t like this
behavior\&.
.PP 
.IP o 
Next, do a make install, followed by a make clean\&.
.PP 
.IP o 
Copy the file XWatch\&.ap from the source directory to 
/usr/lib/X11/app\-defaults/XWatch\&. Edit the file and state your 
favorite settings\&.
.PP 
.IP o 
Next, start the program xwatch with some file arguments in 
your logfiles directory\&. If you\(cq\&re satisfied with the appearance and 
workings of xwatch, add the invocation to your script that starts
an X session\&.
.PP 
endit()
.PP 

.SH "Chapter 5: Copyright"

.PP 
XWatch \- a tool to monitor logfiles and display new logs in an X window\&.  
Copyright (C) 1995 Karel Kubat\&.  All rights reserved\&.
.PP 
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version\&.
.PP 
You may link this software with XForms (Copyright (C) by T\&.C\&. Zhao and
Mark Overmars) and distribute the resulting binary, under the
restrictions in clause 3 of the GPL, even though the resulting binary is
not, as a whole, covered by the GPL\&. (You still need a separate license
to do so from the owner (s) of the copyright for XForms, however)\&.  If a
derivative no longer requires XForms, you may use the unsupplemented GPL
as its license by deleting this paragraph and therefore removing this
exemption for XForms\&.
.PP 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\&.  See the
GNU General Public License for more details\&.
.PP 
You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc\&., 59 Temple Place, Suite 330, Boston, MA  02111\-1307 USA