Provided by: xwatch_2.11-16_amd64 bug

XWatch

       The Logfiles Watcher"

Karel Kubat (karel@icce.rug.nl)

       State University of Groningen
       Westerhaven 16, 9718 AW Groningen
       The Netherlands"

1996

Chapter 1: Introduction

       XWatch is a small program that I wrote to monitor logfiles and to see any changes directly
       (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’s  window.  That’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’ window. I removed this code,
       almost no-one uses it.)

       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’ but who don’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’s distribution.

       Debian  maintainer  note:  XWatch  doesn’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

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:

       startit()

       o      ordinary files, no sockets, directory names,

       o      which are not binary files.

       endit()

       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:

       startit()

       o      -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.

       o      -geometry geom: Specifies the display geometry, a-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.

       o      -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.

       o      -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.

       o      -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.

       o      -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.

       o      -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.

       o      -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.

       o      -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.

       o      -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.

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

       o      -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 |.

       o      -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.

       o      -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.

       o      -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).

       endit()

       Debian Maintainer’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.

       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:

       startit()

       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.

       o      /usr/lib/X11 should point to /usr/X11/lib/X11.

       endit()

       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:

       startit()

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

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

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

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

       endit()

       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.

Chapter 3: Obtaining xwatch

       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.

       To unpack the archive, change-dir to your `sources’ directory (e.g.,  /usr/local/src)  and
       type

       tar xvzf /where/ever/you/put/it/xwatch-X.YY.tar.gz

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

Chapter 4: Compiling xwatch

       Follow these steps.

       startit()

       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.

       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’t like this behavior.

       o      Next, do a make install, followed by a make clean.

       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.

       o      Next, start the program xwatch with some file arguments in your logfiles directory.
              If  you’re satisfied with the appearance and workings of xwatch, add the invocation
              to your script that starts an X session.

       endit()

Chapter 5: Copyright

       XWatch - a tool to monitor logfiles and display new logs in an X  window.   Copyright  (C)
       1995 Karel Kubat.  All rights reserved.

       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.

       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.

       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.

       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

                                                                                        XWatch ()