mailto(karel@icce.rug.nl)

report(\
XWatch nl() \
The Logfiles Watcher)
(Karel Kubat (karel@icce.rug.nl) nl() \
State University of Groningen nl() \
Westerhaven 16, 9718 AW Groningen nl() \
The Netherlands)
(1996)

chapter(Introduction) 

    tt(XWatch) is a small program that I wrote to monitor logfiles and to see
    any changes bf(directly) (instead of having to read all the logs after a
    breakin or a crash). tt(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
    tt(xwatch)'s window. That's all there is to it. The appearance of the
    tt(xwatch) window can furthermore be modified via command line flags or
    via an application defaults file. (Older versions of tt(XWatch) had a
    button to activate an `options' window. I removed this code, almost no-one
    uses it.)

    tt(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 tt(Makefile), contained in tt(xwatch)'s distribution.

chapter(Using xwatch)

    You typically start tt(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 tt(/usr/X11/lib/X11/xdm/Xsession)). The command that starts
    tt(xwatch) is something like

verb(\
 xwatch [options] files &
) 

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

    startit()

	it() ordinary files, no sockets, directory names,

	it() 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, tt(xwatch) warns about the
    file not being acceptable and deletes it from its list of names.

sect(Options to the xwatch program) 

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

    startit()

	it() tt(-border) em(nr):  Specifies whether tt(xwatch) should start
        with a border. The em(nr) must be 0 or 1. When you start tt(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 tt(xwatch) from my window manager tt(fvwm). 
        
        it() tt(-geometry) em(geom): Specifies the display geometry, \'a-la 
        other X programs. You can express the geometry in terms of em(WxH) 
        (width by height), optionally postfixed by em(+X+Y) (x and y offset) 
        or em(-X-Y) (offsets relative to the lower right corner) and other 
        combinations. 
        
        Note that previous switches that emulated the geometry specification, 
        such as tt(-xpos) and tt(-height), are now obsolete. Use the geometry 
        setting.
        
        it() tt(-fg) em(color) and tt(-bg) em(color): These options define the 
        default foreground and background of the watch window.
        
        Note that previous switches, such as tt(-bred) and tt(-bblue), are now 
        obsolete. 

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

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

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

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

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

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

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

	it() tt(-printversion) em(nr): Controls whether tt(xwatch) prints its
        version number and copyright notice upon startup in the watch window.

        it() tt(-gag) em(text): This option, when present, prevents all lines 
        with em(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 tt(|).
        
        it() tt(-colorstring) em(col:string): This option causes lines that 
        contain tt(string) to be displayed using the specified color.
        The string is matched literally. 
        E.g., if you use the option tt(-colorstring blue:connection) then 
        all lines containing tt(connection) are displayed in pure blue.
        
        You can specify several colorstrings by separating all options with a 
        | character, as in tt(-colorstring blue:connection|red:error). Note 
        that, for reasons of shell expansion, you should quote such options on 
        the commandline.
        
        it() tt(-title) em(name): This option sets the window title of the 
        watch window. Note that the title will only be visible when tt(border) 
        is not 0. This option may be useful if you have several XWatch 
        windows, monitoring different things.
        
        it() tt(-ignore) em(fileA|fileB|fileC|...): This option is handy if 
        you start XWatch with a wildcard file argument, but when you want 
        XWatch bf(not) to process some files. The tt(-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, tt(frank@icce.rug.nl) for the code).

    endit()
    
    Before you extensively use the options, create an application defaults
    file tt(/usr/lib/X11/app-defaults/XWatch). You can do so by copying the
    file tt(XWatch.ap), extracted from the archive, to
    tt(/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 tt(/usr/lib/X11/app-defaults).  In
    that case, you should create the following links:

    startit()

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

	it() tt(/usr/lib/X11) should point to tt(/usr/X11/lib/X11).

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

sect(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 tt(/var/adm) normally in blue text; but you
    want to see tt(/var/adm/critical) (critical messages from applications) in
    yellow and tt(/var/adm/auth) (authentification messages) in red. In that
    case, the course to follow would be:

    startit()

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

	it() The color for tt(/var/adm/critical) should be yellow.  Hence, the
        first file argument would be tt(/var/adm/critical:yellow).

	it() The color for file tt(/var/adm/auth) should be red, hence the
        second file argument would be tt(/var/adm/auth:red).

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

    Such a commandline would cause tt(xwatch) to complain about the multiple
    presence of tt(/var/adm/critical) (once from the separate argument, and
    once from the wildcard argument) and similarly about tt(/var/adm/auth). If
    this bothers you, turn off the initial warnings (e.g., using
    tt(-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 tt(-colorstring) for more 
    information.
    
COMMENT(**** Leave this tag in place, it's used to generate the INSTALL
             file:
STARTINSTALL )

IFDEF(INSTALL)
(report(XWatch: short installation guide)()())
()

chapter(Obtaining xwatch) 

    tt(XWatch) can be obtained at the ftp site url(tt(ftp.icce.rug.nl))
    (ftp://ftp.icce.rug.nl), in the directory url(tt(/pub/unix))
    (ftp://ftp.icce.rug.nl/pub/unix), as the file tt(xwatch-X.YY.tar.gz).
    tt(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.,
    tt(/usr/local/src)) and type

verb(\
tar xvzf /where/ever/you/put/it/xwatch-X.YY.tar.gz
) 

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

chapter(Compiling xwatch)

IFDEF(INSTALL)(\

    This file is automatically generated from tt(doc/xwatch.yo). Please 
    also read the full docs in HTML format as tt(doc/xwatch.html) or in LaTeX 
    format as tt(doc/xwatch.tex). A poor-mans document is tt(doc/xwatch.txt), 
    that's plain ASCII for those who can't handle HTML or LaTeX.
    )
    ()

    Follow these steps.

    startit()

	it() You will need the XForms library and include files to compile
        tt(xwatch).  Check the tt(Makefile) in the tt(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.

	it() In the tt(src) subdirectory, edit the tt(Makefile) and adjust
        some defines at the top. E.g., a tt(make install) copies the binary by
        default to tt(/usr/local/X11/bin); adjust that if you don't like this
        behavior.

	it() Next, do a tt(make install), followed by a tt(make clean).
        
        it() Copy the file tt(XWatch.ap) from the source directory to 
        tt(/usr/lib/X11/app-defaults/XWatch). Edit the file and state your 
        favorite settings.
        
        it() Next, start the program tt(xwatch) with some file arguments in 
        your logfiles directory. If you're satisfied with the appearance and 
        workings of tt(xwatch), add the invocation to your script that starts
	an X session.

    endit()

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