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