.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 
\f(CWXWatch\fP 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)\&. \f(CWXWatch\fP 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
\f(CWxwatch\fP\(cq\&s window\&. That\(cq\&s all there is to it\&. The appearance of the
\f(CWxwatch\fP window can furthermore be modified via command line flags or
via an application defaults file\&. (Older versions of \f(CWXWatch\fP had a
button to activate an `options\(cq\& window\&. I removed this code, almost no\-one
uses it\&.)
.PP 
\f(CWXWatch\fP 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 \f(CWMakefile\fP, contained in \f(CWxwatch\fP\(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 \f(CWxwatch\fP 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 \f(CW/usr/X11/lib/X11/xdm/Xsession\fP)\&. The command that starts
\f(CWxwatch\fP 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 \f(CWxwatch\fP in the background\&. The
files to watch are typically in the directory \f(CW/var/adm/\fP: files which
are created by the syslog daemon (see the file \f(CWsyslogd\&.conf\&.SAMPLE\fP in
the distribution for an example)\&.  \f(CWXWatch\fP accepts only filenames which
are:
.PP 
.IP o 
ordinary files, no sockets, directory names,
.IP 
.IP o 
which are not binary files\&.
.IP 
Other files as stated on the commandline are not monitored\&. When any
`non\-proper\(cq\& file is given on the commandline, \f(CWxwatch\fP 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 \f(CWxwatch\fP without arguments to see what is
supported\&. All options can also be stated in the file
\f(CW/usr/lib/X11/app\-defaults/XWatch\fP as X resources (see the file
\f(CWXWatch\&.ap\fP as an example)\&. In the following enumeration, a \fInr\fP
denotes a number:
.PP 
.IP o 
\f(CW\-border\fP \fInr\fP:  Specifies whether \f(CWxwatch\fP should start
with a border\&. The \fInr\fP must be 0 or 1\&. When you start \f(CWxwatch\fP
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 \f(CWxwatch\fP from my window manager \f(CWfvwm\fP\&. 
.IP 
.IP o 
\f(CW\-geometry\fP \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\&. 
.IP 
Note that previous switches that emulated the geometry specification, 
such as \f(CW\-xpos\fP and \f(CW\-height\fP, are now obsolete\&. Use the geometry 
setting\&.
.IP 
.IP o 
\f(CW\-fg\fP \fIcolor\fP and \f(CW\-bg\fP \fIcolor\fP: These options define the 
default foreground and background of the watch window\&.
.IP 
Note that previous switches, such as \f(CW\-bred\fP and \f(CW\-bblue\fP, are now 
obsolete\&. 
.IP 
.IP o 
\f(CW\-printtime\fP \fInr\fP: Defines whether \f(CWxwatch\fP should prefix
any info on the watched files with a timestamp\&. The \f(CWnr\fP can be 0 or
zero; the timestamp is printed when \fInr\fP is 1\&.
.IP 
.IP o 
\f(CW\-printname\fP \fInr\fP: Defines whether \f(CWxwatch\fP should prefix
any info on the watched files with the filename\&. The \fInr\fP is again a
flag, 0 or 1\&.
.IP 
.IP o 
\f(CW\-newline\fP \fInr\fP: Defines whether \f(CWxwatch\fP should let a
newline follow the time and/or filename stamp, so that the actual
information is displayed on its own line\&.
.IP 
.IP o 
\f(CW\-interval\fP \fInr\fP: Defines the scanning interval\&.  Each \fInr\fP
seconds, \f(CWxwatch\fP will check if new information has arrived on the
watched files\&. The \fInr\fP may be between 1 and 30 seconds\&. 
.IP 
.IP o 
\f(CW\-fontsize\fP \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\&.
.IP 
.IP o 
\f(CW\-fontstyle\fP \fInr\fP: Defines the style of the used font\&. The
\fInr\fP is a number between 0 and 15 (0 being the default)\&. Start
\f(CWxwatch\fP without arguments or read the application defaults file to
see what fonts the numbers choose\&.
.IP 
.IP o 
\f(CW\-firstwarnings\fP \fInr\fP: Defines whether \f(CWxwatch\fP should
print initial warnings into the watch window\&.  E\&.g\&., you might like to
set \f(CWfirstwarnings\fP to zero, and then start \f(CWxwatch\fP with the file
argument \f(CW/var/adm/*\fP\&.  Warnings about, e\&.g\&., \f(CWutmp\fP being a
binary file would then be suppressed\&.
.IP 
.IP o 
\f(CW\-printversion\fP \fInr\fP: Controls whether \f(CWxwatch\fP prints its
version number and copyright notice upon startup in the watch window\&.
.IP 
.IP o 
\f(CW\-gag\fP \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 \f(CW|\fP\&.
.IP 
.IP o 
\f(CW\-colorstring\fP \fIcol:string\fP: This option causes lines that 
contain \f(CWstring\fP to be displayed using the specified color\&.
The string is matched literally\&. 
E\&.g\&., if you use the option \f(CW\-colorstring blue:connection\fP then 
all lines containing \f(CWconnection\fP are displayed in pure blue\&.
.IP 
You can specify several colorstrings by separating all options with a 
| character, as in \f(CW\-colorstring blue:connection|red:error\fP\&. Note 
that, for reasons of shell expansion, you should quote such options on 
the commandline\&.
.IP 
.IP o 
\f(CW\-title\fP \fIname\fP: This option sets the window title of the 
watch window\&. Note that the title will only be visible when \f(CWborder\fP 
is not 0\&. This option may be useful if you have several XWatch 
windows, monitoring different things\&.
.IP 
.IP o 
\f(CW\-ignore\fP \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 \f(CW\-ignore\fP 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, \f(CWfrank@icce\&.rug\&.nl\fP for the code)\&.
.IP 
\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 \f(CW/usr/lib/X11/app\-defaults/XWatch\fP\&. You can do so by copying the
file \f(CWXWatch\&.ap\fP, extracted from the archive, to
\f(CW/usr/lib/X11/app\-defaults/XWatch\fP\&. The comments in the distributed 
application defaults file explain what you can configure and show 
examples\&. 
.PP 
Some systems do not have the directory \f(CW/usr/lib/X11/app\-defaults\fP\&.  In
that case, you should create the following links:
.PP 
.IP o 
\f(CW/usr/X11\fP should point to your X11 distribution; e\&.g\&.  to
\f(CW/usr/X11R6\fP\&. That way, you always have e\&.g\&.  \f(CW/usr/X11/bin\fP, even
after upgrading your X11 distribution\&. All that is needed is one new
link\&.
.IP 
.IP o 
\f(CW/usr/lib/X11\fP should point to \f(CW/usr/X11/lib/X11\fP\&.
.IP 
Then edit the file \f(CWXWatch\fP in the application defaults directory, and
follow the instructions therein to define your favorite settings\&.  If you
need to start \f(CWxwatch\fP 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 \f(CW/var/adm\fP normally in blue text; but you
want to see \f(CW/var/adm/critical\fP (critical messages from applications) in
yellow and \f(CW/var/adm/auth\fP (authentification messages) in red\&. In that
case, the course to follow would be:
.PP 
.IP o 
The default foreground color would be blue\&. You could set this
with the flags \f(CW\-fg blue\fP, or in the application
defaults file\&.
.IP 
.IP o 
The color for \f(CW/var/adm/critical\fP should be yellow\&.  Hence, the
first file argument would be \f(CW/var/adm/critical:yellow\fP\&.
.IP 
.IP o 
The color for file \f(CW/var/adm/auth\fP should be red, hence the
second file argument would be \f(CW/var/adm/auth:red\fP\&.
.IP 
.IP o 
The following arguments would be the files, using the standard
foreground (blue): \f(CW/var/adm/*\fP, without any extra color
specifications\&.
.IP 
Such a commandline would cause \f(CWxwatch\fP to complain about the multiple
presence of \f(CW/var/adm/critical\fP (once from the separate argument, and
once from the wildcard argument) and similarly about \f(CW/var/adm/auth\fP\&. If
this bothers you, turn off the initial warnings (e\&.g\&., using
\f(CW\-firstwarnings 0\fP 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 \f(CW\-colorstring\fP for more 
information\&.
.PP 

.SH "Chapter 3: Obtaining xwatch"

.PP 
\f(CWXWatch\fP can be obtained at the ftp site \f(CWftp\&.icce\&.rug\&.nl\fP, in the directory \f(CW/pub/unix\fP, as the file \f(CWxwatch\-X\&.YY\&.tar\&.gz\fP\&.
\f(CWX\&.YY\fP 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\&.,
\f(CW/usr/local/src\fP) 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 \f(CWxwatch\fP and check there\&.
You will find a subdirectory \f(CWsrc\fP with the full sources\&.
.PP 

.SH "Chapter 4: Compiling xwatch"

.PP 
Follow these steps\&.
.PP 
.IP o 
You will need the XForms library and include files to compile
\f(CWxwatch\fP\&.  Check the \f(CWMakefile\fP in the \f(CWsrc\fP 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\&.
.IP 
.IP o 
In the \f(CWsrc\fP subdirectory, edit the \f(CWMakefile\fP and adjust
some defines at the top\&. E\&.g\&., a \f(CWmake install\fP copies the binary by
default to \f(CW/usr/local/X11/bin\fP; adjust that if you don\(cq\&t like this
behavior\&.
.IP 
.IP o 
Next, do a \f(CWmake install\fP, followed by a \f(CWmake clean\fP\&.
.IP 
.IP o 
Copy the file \f(CWXWatch\&.ap\fP from the source directory to 
\f(CW/usr/lib/X11/app\-defaults/XWatch\fP\&. Edit the file and state your 
favorite settings\&.
.IP 
.IP o 
Next, start the program \f(CWxwatch\fP with some file arguments in 
your logfiles directory\&. If you\(cq\&re satisfied with the appearance and 
workings of \f(CWxwatch\fP, add the invocation to your script that starts
an X session\&.
.IP 

.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