EventMonAPI(3X)

NAME
     EventMon API - Programmer's Guide

SYNOPSIS
      #include <eventmonapi.h>

      int EVMONAPI emapiIsDaemonInstalled();

      int EVMONAPI emapiIsDaemonStarted();

      int EVMONAPI emapiDeclareDaemonUnload();

      int EVMONAPI emapiDeclareDaemonReloadConfig();

      int EVMONAPI emapiSendEvent(char *hostname_from,unsigned
                long time,int etype,int epri,char *eventbuffer);


DESCRIPTION
     EventMon API is a set of functions for connecting to and communicating
     with Event Monitor daemon  (see eventmond(1M) for more details).
     (EventMon daemon is a system daemon responsible for intercepting all
     system events messages from syslog daemon, filtering and buffering them).
     This API allows different applications to communicate with EventMon
     daemon in order to do the following:

     check installed binary image of EventMon daemon in system directory
     (function emapiIsDaemonInstalled());

     check if an instance of EventMon daemon is running in system memory
     (function emapiIsDaemonStarted());

     declare "unload" event to EventMon daemon (function
     emapiDeclareDaemonUnload());

     declare "reload filter configuration" event to EventMon daemon (function
     emapiDeclareDaemonReloadConfig());

     send a particular event message to EventMon daemon (function
     emapiSendEvent(...));

     This functionalities are provided via set of functions declared in
     eventmonapi.h file. All functions are implemented in library
     libeventmon.so.  EventMon API functions use two named pipes, provided by
     EventMon daemon, and internal commands for communication with EventMon
     daemon.  EventMon API quite a small set of error codes in functions.


int EVMONAPI emapiIsDaemonInstalled();
     This function allows to check location of a binary file of EventMon
     daemon in system directory.

     Parameter(s) - none
     Return value - Non-zero value indicates that executable file of EventMon
     daemon exists in system directory (/usr/etc/eventmond). Zero means that
     EventMon executable doesn't exist in system directory.


int EVMONAPI emapiIsDaemonStarted();
     This function allows to check if an instance of EventMon daemon exists in
     memory.  Application might use this function before using other functions
     from EventMon API.

     Parameter(s): none
     Return value: integer. Non-zero value indicates that an instance of
     EventMon daemon is started and exists in memory. Zero means that EventMon
     is not started.



int EVMONAPI emapiDeclareDaemonUnload();
     This function allows to declare "unload" notification to an instance of
     EventMon daemon. The "declare" term means that after this function call
     EventMon daemon will start unload process.  Due to the fact that this
     process can take up to 2 seconds, EventMon daemon can remain in memory
     immediately after emapiDeclareDaemonUnload call until this "unload"
     process is not completed.

     Parameter(s): none
     Return value: integer. Non-zero value indicates a successful passed
     "unload" notification to EventMon daemon.  Zero is returned on error.
     Important notice: application must have "root" permissions/privileges to
     call this function.


int EVMONAPI emapiDeclareDaemonReloadConfig();
     This function allows to declare "reload configuration info" notification
     to an instance of EventMon daemon. This declaration means that after this
     call EventMon daemon will start "reload configuration info" process. This
     process includes three steps:

     1. dropping all filter information from internal EventMon memory tables;
     2. connection to system tables which includes filtering information;
     3. adjustment of internal EventMon memory tables according system
     information.

     This function call carries the same functionality as following shell
     command:
          "kill -HUP eventmon_pid"
     Parameter(s): none
     Return value: integer. Non-zero value - successful pass of "reload
     configuration info" notification to EventMon daemon. On error the return
     value is zero.
     Important notice: application must have "root" permissions/privileges to
     call this function.


int EVMONAPI emapiSendEvent(char *hostname_from,
unsigned long time,int etype,int epri,char *eventbuffer);
     This function allows to pass a message with particular sequence number
     and priority/facility code information to EventMon.

     Parameter(s):
     char *hostname    - host name from coming event
                         (NULL for localhost)
     unsigned long     - timehost name from coming event
                         (NULL for localhost)
     int etype         - valid event type value (must be non-zero value)
     int epri          - valid priority/facility code (see sys/syslog.h
                         file)
     char *eventbuffer - valid ASCIZ buffer with event message
                         string (must be a valid string pointer
                         and have non zero size)

     Return value: integer. Non-zero value indicated successful pass of a
     message to EventMon daemon for processing.  Zero - an error.

     Important notice: size of eventbuffer can't be more than
     EVMONAPI_MAXEVENTSIZE (defined in evmonapi.h file) bytes, no more than
     64K bytes.

      Sample:

      #include <stdio.h>
      #include <sys/syslog.h>
      #include <eventmonapi.h>

      main()
      { if(!emapiIsDaemonStarted())
        { printf("EventMon daemon not started!\n");
          exit(0);
        }
        return emapiSendEvent("legalov.sgi.com",0,0x20101C,
               LOG_MAKEPRI(LOG_USER,LOG_INFO), "Hello world!");
      }

SEE ALSO
     eventmond(1M)