NAME

       libwulf - xmlsysd client library

SYNOPSIS

       libwulf.a

DESCRIPTION

       libwulf.a  is  the core common library required by wulfstat and wulflogger, two xmlsysd clients that poll
       and display various statistics from a cluster in a user-controllable  loop.   libwulf  contains  routines
       that  open  and  parse  a  wulfhosts  (cluster/lan  descriptor)  file, establish xmlsysd connections in a
       threaded subtask to all hosts in the wulfhosts file, and in parallel  with  this  initialize  and  update
       selected  statistics.   libwulf  functions form an API adequate to support many kinds of toplevel log and
       gui applications reasonably efficiently.

       The best way to develop an application using libwulf is to examine one of the existing applications  such
       as wulflogger.  The steps are roughly as follows:

         * Initialize libxml

         * Allocate various linked lists using the provided linked list routines

         * Read and parse the wulfhosts file

         *  Set the dctl (display control) state for all hosts.  This struct MUST correspond to the state of the
       xmlsysd on the hosts.

         * Connect to all hosts, generally in a threaded loop that runs in parallel with any display process (so
       that if a host goes down the display task does not block).

         * Initialize all host-derived values from an initial xmlsysd return

         * Enter a polling work loop that sends all hosts the "send" commmand, updates all host  derived  values
       and  then  sleeps.  This loop can contain branches that alter dctl state, alter the display, or do pretty
       much whatever you want with the data retrieved.

         * Display or otherwise utilize the per-host data.

         * Exit (cleanly or otherwise) on request.

DCTL FLAGS

       The following is the dctl struct currently used by libwulf.  The contents are all flags that can take  on
       values  of  0  (no or false) or not-zero (yes or true).  There is a fairly straightforward correspondance
       between dctl state flags and throttleable xmlsysd tags and their (possibly sub-tagged) contents.

        typedef struct {

          int compress;  /* Do we compress xml output? */
          int whitespace;     /* Do we squeeze out whitespace? */

          /*
           * All the following toggle various components of the return.  Some of
           * these are only needed "once" in a typical monitoring session anyway
           * and can be pulled from the init return (which always sends
           * "everything").  Future developers should note the 1:1 correspondance
           * between many of these flags and "init_XXXX.c" and "update_XXXX.c"
           * sources and calls.
           */

          /* system call stuff */
          int identity;  /* Do we update system identity? */
          int time;      /* Do we update system time? */
          int users;          /* Do we update system pids? */
          /* proc-derived stuff */
          int cpuinfo;        /* Do we update proc cpuinfo? */
          int loadavg;        /* Do we update proc loadavg? */
          int meminfo;        /* Do we update proc meminfo? */
          int net;       /* Do we update proc net? */
          int stat;      /* Do we update proc stat? */
          int sysvipc;        /* Do we update proc shared memory stuff? */
          int uptime;         /* Do we update proc uptime? */
          int version;        /* Do we update proc (kernel) version? */
          /* Processes (in /proc/XXXXX where XXXXX is a pid) */
          int pids;      /* Do we update pids at all? */
          int running;        /* Running PIDs or all? */
          int root;      /* Including those owned by root? */
          List *userlist;     /* A linked list of usernames to watch */
          List *tasklist;     /* A linked list of tasknames to watch */

        } Dctl;

SEE ALSO:

       wulfstat(1), wulflogger(1)

PUBLICATION RULES

       libwulf.a can be modified and used at will by any user, provided that:

         a) The original copyright notices are maintained and that the source, including all  modifications,  is
       made publically available at the time of any derived publication.  This is open source software according
       to the precepts and spirit of the Gnu Public License.  See the accompanying file COPYING, which also must
       accompany any redistribution.

         b) The author of the code (Robert G. Brown) is appropriately acknowledged and referenced in any derived
       use or publication.

         c)  Full  responsibility for the accuracy, suitability, and effectiveness of the program rests with the
       users and/or modifiers.  As is clearly stated in the accompanying copyright.h:

       THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES  WITH  REGARD  TO  THIS  SOFTWARE,  INCLUDING  ALL  IMPLIED
       WARRANTIES  OF  MERCHANTABILITY  AND  FITNESS,  IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
       SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA  OR
       PROFITS,  WHETHER  IN  AN  ACTION  OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
       CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

ACKNOWLEDGEMENTS

       None to speak of now, but a good place to comply with b) above later, if you hack  this  code.   Well,  I
       should  probably acknowledge the essential help of Icon (Konstantin Raibetsev) and Seth Vidal, the entire
       beowulf list, and various books on xml, network programming (e.g. Stevens) and a cast of  thousands.   So
       let's assume that I just did;-)

       GPL  2b;  see  the  file  COPYING that accompanies the source of this program.  This is the "standard Gnu
       General Public License version 2 or  any  later  version",  with  the  one  minor  (humorous)  "Beverage"
       modification  listed  below.   Note  that this modification is probably not legally defensible and can be
       followed really pretty much according to the honor rule.

       As to my personal preferences in beverages, red wine is great, beer  is  delightful,  and  Coca  Cola  or
       coffee  or  tea  or  even  milk  acceptable  to those who for religious or personal reasons wish to avoid
       stressing my liver.

       The Beverage Modification to the GPL:

       Any satisfied user of this software shall, upon meeting the primary author(s) of this  software  for  the
       first  time  under  the  appropriate  circumstances,  offer  to  buy him or her or them a beverage.  This
       beverage may or may not be alcoholic, depending on the personal ethical and moral views of  the  offerer.
       The  beverage  cost  need  not  exceed  one  U.S.  dollar  (although  it certainly may at the whim of the
       offerer:-) and may be accepted or declined with no further obligation on the part of the offerer.  It  is
       not necessary to repeat the offer after the first meeting, but it can't hurt...

LIBWULF                                  Copyright 2004 Robert G. Brown                               LIBWULF(3)