xenial (1) xwatch.1.gz

Provided by: xwatch_2.11-15build1_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:

       o      ordinary files, no sockets, directory names,

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

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

              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:

       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.

              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:

       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.

              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.

       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.

       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 ()