.TH EventMonAPI 3X
.SH NAME
EventMon API - Programmer's Guide
.SH SYNOPSIS
.nf
 #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);

.fi
.SH DESCRIPTION
.P
\f3EventMon API\f1 is a set of functions for connecting to and communicating 
with Event Monitor daemon  (see \f2eventmond\f1(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:
.sp 1
check installed binary image of EventMon daemon in system directory (function emapiIsDaemonInstalled());
.sp 1
.br 
check if an instance of EventMon daemon is running in system memory (function emapiIsDaemonStarted());
.sp 1 
.br 
declare "unload" event to EventMon daemon (function emapiDeclareDaemonUnload()); 
.sp 1
.br
declare "reload filter configuration" event to EventMon daemon (function emapiDeclareDaemonReloadConfig());
.sp 1 
.br
send a particular event message to EventMon daemon (function emapiSendEvent(...));
.sp 1
.br
This functionalities are provided via set of functions declared in
\f3eventmonapi.h\f1 file. All functions are implemented in library
\f3libeventmon.so\f1.
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. 

.SH int EVMONAPI emapiIsDaemonInstalled();
.P
This function allows to check location of a binary file of EventMon daemon in system directory.
.sp 1 
Parameter(s) - none   
.br
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. 

.SH int EVMONAPI emapiIsDaemonStarted(); 
.P
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. 
.sp 1 
Parameter(s): none 
.br
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. 


.SH 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. 
.sp 1 
Parameter(s): none 
.br
Return value: integer. Non-zero value indicates a successful passed "unload" notification to EventMon daemon.
Zero is returned on error. 
.br
Important notice: application must have "root" permissions/privileges to call this function. 

.SH 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: 
.sp 1 
1. droping all filter information from internal EventMon memory tables; 
.br
2. connection to system tables which includes filtering information; 
.br
3. adjustment of internal EventMon memory tables according system information.
.br
.sp 1 
This function call carries the same functionality as following shell command: 
.nf
     "kill -HUP eventmon_pid" 
.fi
Parameter(s): none
.br
Return value: integer. Non-zero value - successful pass of "reload 
configuration info" notification to EventMon daemon. On error the return value is zero. 
.br
Important notice: application must have "root" permissions/privileges to call this function. 
.br

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

.P
This function allows to pass a message with particular sequence number and priority/facility code
information to EventMon. 
.sp 1 
Parameter(s): 
.br
.nf
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) 
.fi
.P
.sp 1 
Return value: integer. Non-zero value indicated successful pass of a message to EventMon daemon for processing.
Zero - an error.
.br
.sp 1
Important notice: size of eventbuffer can't be more than EVMONAPI_MAXEVENTSIZE (defined in evmonapi.h file) bytes,
no more than 64K bytes. 
.br
.sp 1
.nf
 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!");
 }
.fi
.SH SEE ALSO

eventmond(1M)