The Event Manager application programming interface (API) provides functions that enable applications to communicate with the Event Manager daemon (eventmond). These functions enable the applications to:
Subscribe events
Unsubscribe events
Log events
Query events
The Event Manager API uses a TCP/IP socket to communicate with the Event Manager daemon. The emgrapi.h file contains the function declarations, and the libemgrapi.so file contains the actual functions.
This chapter describes the functions that the Event Manager API contains. Chapter 3, “Creating Producer, Subscriber, and Consumer Applications”, describes how to use the functions to create producer, subscriber, and consumer applications.
The Event Manager API functions use the following special data structures:
Event structure
GeneralBlock structure
The API functions use a structure called event (EmgrEvent_t) to pass event information. The event structure includes a fixed portion (the event header) and a variable portion (the event data). The event header contains information about the event (application that created it, host where it originated, time that it occurred, and so on), and the event data contains the actual event.
 | Note: An event structure contains all public data for the event. All private data that the API control layer requires is stored in a private event control structure that contains the event structure as its first element. Do not directly allocate memory for an event structure; use the emgrAllocEvent() API function to allocate event resources. |
Figure 2-1 shows the layout of the event structure.
Table 2-1 describes the fields that the event header contains.
Table 2-1. Event Header Fields
Field | Description | Size |
|---|---|---|
evClass | Event class ID number | 4 bytes |
evType | Event type ID number that is unique to each application | 4 bytes |
flags | Internal flags that indicate how to handle the message | 2 bytes |
version | Event version number that is specific to each application | 2 bytes |
timestamp | Time that the event occurred | 8 bytes |
uid | User ID number of the process that generated the event | 4 bytes |
evid | Event ID number | 4 bytes |
header_size | Size of the event header plus event body | 4 bytes |
total_size | Size of the entire event | 4 bytes |
Field | Description | Size |
|---|---|---|
source | Hostname (including domain name) of the system that generated the event | Variable (included in a zero- terminated string) |
appname | Application that owns the event (for example, Kernel or UNIX) | Variable (included in a zero terminated string) |
origin | Application that generated the event (for example, SYSLOG) | Variable (included in a zero terminated string) |
The event payload portion of the event structure contains a linked list of “items” that are formatted as (name, value) pairs. The name portion is a zero-terminated string that acts like an additional field in the event structure. The value portion is a typed value that the Event Manager can use to filter expressions or a consumer application can use as event data.
You must enter information in the following fields before you can send event information via the Event Manager API:
The source field must be set to the hostname of the system where the event originates.
The appname field must be set to the application that is sending the event (for example, ESP, CXFS, etc.).
The following definitions in the emgrapi.h file create the event structure:
Definition of the event header:
typedef struct EmgrEventHeader { int32_t evClass; /* Event Class number (application specific) */ int32_t evType; /* Event Type number (application specific) */ int16_t flags; /* Event flags */ int16_t version; /* Event Version (application specific) */ int64_t timestamp; /* Event Time (GMT) */ int32_t uid; /* User ID of a process which sends an event */ uint32_t evid; /* Event id <16 bit sq number><16 bit random> */ int32_t header_size; /* size of fixed and variable parts of header */ int32_t total_size; /* size of entire event including header */ } EmgrEventHeader_t;Definition of the event body:
typedef struct EmgrEvent { /* Fixed portion of public event data */ EmgrEventHeader_t header; /* Variable portion of public event data */ char *source; /* fully qualified local hostname */ char *appname; /* Name of application that owns this event */ char *origin; /* Name of application that logged this event */ /* Private API data is appended here * * Note: Never directly allocate memory for an EmgrEvent struct. * Always use the emgrAllocEvent() function to allocate an event struct. */ } EmgrEvent_t;
The GeneralBlock structure is an abstract structure that defines data within an event structure. The following definition in the emgrGb.h file creates the GeneralBlock structure:
typedef struct GeneralBlock {
int32_t type;
int32_t length;
void *pValue;
char tag[1];
} GeneralBlock_t;
|
The GeneralBlock structure provides a way to represent (name, value) pairs for various types of data. The structure currently supports strings, binary data, and file data; however, it is an open structure that can support other types if needed. The event data is a linked list of GeneralBlock structures.
When a data item in an event structure is a file, there is a GbFileValue structure that defines it. The GbFileValue structure contains the size of the file data and related information, the modification time of the file, the path to the file, and the raw file data. The following definition in the emgrGb.h file creates the GbFileValue structure:
typedef struct GbFileValue {
int32_t size; /* size of the static attributes (size and
mod time) + the length of the path and file */
char modTime[24];
char *path;
int8_t *pContent;
} GbFileValue_t;
|
The API functions have the following categories:
Event manipulation functions:
Creation/definition functions
Access functions
Subscription manipulation functions
Transmission/execution functions
Configuration functions
Table 2-3 lists the functions that belong to each category and the type of application (producer, subscriber, and/or consumer) that uses each function. Descriptions of the individual functions appear in alphabetical order after the table.
Table 2-3. API Function Categories
Category | Function | Used By[a] |
|---|---|---|
Event manipulation (creation/definition) | emgrAddGbToEvent() | P |
| emgrAddIntItemToEvent() | P/S |
| emgrAddItemToEvent() | P/S |
| emgrAddTaggedDataToEvent() | P |
| emgrAddTaggedFileToEvent() | P |
| emgrAddDataToEvent() | P |
| emgrAddFileToEvent() | P |
| emgrAllocEvent() | P |
| emgrCloneEvent() | C |
| emgrCloneGb() | C |
| emgrFreeEvent() | P |
| emgrGetEventItem() | C |
Event manipulation
(creation/definition) | emgrGetFirstEventGb() | C |
| emgrGetFirstEventItem() | C |
| emgrGetNextEventGb() | C |
| emgrGetNextEventItem() | C |
| emgrNewQuery() | P/S |
| emgrSetToForward() | P |
| emgrShmCliInitEvent() | C |
| emgrShmInitEvent() | C |
Event manipulation (access) | emgrBuildQSearch() | C |
| emgrPrintEvent() | P/S/C |
| emgrSearchGb() | C |
| emgrCheckEvent() | P/S/C |
| emgrAddSubscribe() | S |
| emgrAddUnsubscribe() | S |
| emgrNewSubscribe() | S |
| emgrNewUnsubscribe() | S |
| emgrSubscribeSpecCntFreq() | S |
| emgrSubscribeSpecDsoConsumer() | S |
| emgrSubscribeSpecExecConsumer() | S |
| emgrSubscribeSpecExecShMemConsumer() | S |
| emgrSubscribeSpecFacility() | S |
| emgrSubscribeSpecForwardConsumer() | S |
| emgrSubscribeSpecPriority() | S |
Subscription manipulation | emgrSubscribeSpecRegexpMap() | S |
| emgrSubscribeSpecTimeFreq() | S |
Transmission/execution | emgrForwardEvent() | P |
| emgrRunQuery() | P/S |
| emgrRunSubscribe() | S |
| emgrRunUnSubscribe() | S |
| emgrSendEvent() | P/S |
Configuration | emgrIsDaemonInstalled() | P/S |
| emgrIsDaemonStarted() | P/S |
| getConfigValue() | P/S |
[a] The “Used By” column indicates the type of application that uses each function (P = producer, S = subscriber, and C = consumer). | ||
The following sections describe the API functions that are available.
int emgrAddDataToEvent(EmgrEvent_t *pEvent,
const void *databuf,
size_t size);
|
The emgrAddDataToEvent() function adds binary data to an event.
Parameters:
| *pEvent | pointer to an event structure | |
| *databuf | pointer to a data buffer (The pointer should be valid while you use the event; producers should free the data buffer memory.) | |
| size | size of the data buffer (in bytes) |
Return value:
Success: 0
Failure:
-1 A processing error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrAddFileToEvent(EmgrEvent_t *pEvent,
const char *path);
|
The emgrAddFileToEvent() function adds the contents of a file to an event.
Parameters:
| *pEvent | pointer to an event structure | |
| *path | pointer to a character string that contains the full pathname of the file |
Return value:
Success: 0
Failure:
-1 A processing error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
17 The file does not exist or could not be opened.
int emgrAddGbToEvent(EmgrEvent_t *pEvent,
struct GeneralBlock *pNewGB);
|
The emgrAddGbToEvent() function adds a GeneralBlock structure to an event.
Parameters:
| *pEvent | pointer to an event structure | |
| *pNewGB | pointer to a GeneralBlock structure to add to the event |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrAddIntItemToEvent(EmgrEvent_t *pEvent,
const char *name,
long value);
|
The emgrAddIntItemToEvent() function converts an integer to a string and adds it to an event.
Parameters:
| *pEvent | pointer to the event structure | |
| *name | pointer to a character string that contains the name of the item | |
| value | integer value to add |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrAddItemToEvent(EmgrEvent_t *pEvent,
const char *name,
const char *value);
|
The emgrAddItemToEvent() function adds an item (named value) to an event.
Parameters:
| *pEvent | pointer to the event structure | |
| *name | pointer to a character string that contains the name of the item | |
| *value | pointer to a character string that contains the value of the item |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
EmgrEvent_t *emgrAddSubscribe(EmgrEvent_t *pEvent,
const char *appname,
int evClass,
int evType,
const char *source,
const char *origin);
|
The emgrAddSubscribe() function adds the next subscription specification to an event that was already allocated with the emgNewSubscribe() function. The emgrAddSubscribe() function also sets specific information for batch subscription processing.
Parameters:
| *appname | pointer to a character string that contains the name of the application that owns the event (has domain over the event class and type) (Set this string to NULL to select events from any application.) | |
| evClass | event class to subscribe (Set this parameter to -1 to select all classes.) | |
| evType | event type to subscribe (Set this parameter to -1 to select all event types.) | |
| *source | pointer to a character string that contains the name of the host or hosts from which to subscribe events (If the string contains more than one host, separate the hosts with spaces and/or commas. If the string is empty or NULL, events are subscribed from the localhost.) | |
| *origin | pointer to a character string that contains the name of the application that logs the event (If the application that sends the events also owns the events, set the origin and appname parameters to the same value or pass an empty string or NULL character pointer to the origin parameter.) |
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
int emgrAddTaggedDataToEvent(EmgrEvent_t *pEvent,
const char *tag,
const void *pBuffer,
size_t size);
|
The emgrAddTaggedDataToEvent() function adds the contents of a data buffer to an event. It also names the data with a tag that you can specify to quickly access the data again. (The tag acts as an item name.)
Parameters:
| *pEvent | pointer to an event structure | |
| *tag | pointer to a character string that contains the tag | |
| *pBuffer | pointer to the buffer of data (This pointer must be valid the entire time that the event is in use.) | |
| size | number of bytes of data in the buffer |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrAddTaggedFileToEvent(EmgrEvent_t *pEvent,
const char *tag,
const char *path);
|
The emgrAddTaggedFileToEvent() function adds the contents of a file to an event. It also names the data block with a tag that you specify so you can quickly access the data again. (The tag acts as an item name.)
Parameters:
| *pEvent | pointer to an event structure | |
| *tag | pointer to a character string that contains the file tag | |
| *path | pointer to a character string that contains the path to the file |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
EmgrEvent_t *emgrAddUnSubscribe(EmgrEvent_t *pEvent,
const char *appname,
int evClass,
int evType,
const char *source,
const char *origin);
|
The emgrAddUnSubscribe() function adds the next unsubscription specification to an event that was already allocated with the emgrNewUnSubscribe() function. The emgrAddUnSubscribe() function also sets specific information for batch event processing.
Parameters:
| *pEvent | pointer to an event structure | |||
| *appname | pointer to a character string that contains the name of the application that owns the event (has domain over the event class and type)
| |||
| evClass | event class to subscribe (Set this parameter to -1 to select all classes.) | |||
| evType | event type to subscribe (Set this parameter to -1 to select all event types.) | |||
| *source | pointer to a character string that contains the name of the host or hosts from which to subscribe events (If the string contains more than one host, separate the hosts with spaces and/or commas. If the string is empty or NULL, events are unsubscribed from the localhost.) | |||
| *origin | pointer to a character string that contains the name of the application that logs the event (If the application that sends the events also owns the events, set the origin and appname parameters to the same value. Set this parameter to empty string or the NULL character pointer to specify any application.) |
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
EmgrEvent_t *emgrAllocEvent(const char *appname,
int evClass,
int evType,
int version,
char *origin);
|
The emgrAllocEvent() function allocates memory for an event.
Parameters:
| *appname | pointer to a character string that contains the name of the application that owns the event | |
| evClass | application-specific event class number (set to 0 if you do not want to specify a class) | |
| evType | application-specific event type number (do not set to 0 or -1) | |
| version | application-specific event version for consumer or producer use (set to 0 if you do not want to specify a version) | |
| *origin | pointer to a character string that contains the name of the application that logs the event (If it is the same as the application that owns the event, set the string to the same string as appname.) |
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
int emgrBuildQSearch(EmgrEvent_t *pEvent); |
The emgrBuildQSearch() function builds the internal search table for an event to enable searches based on item tags. Normally, you do not need to use the function because the Event Manager calls it when necessary on the consumer side.
Parameters:
| *pEvent | pointer to the event structure |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrCheckEvent(const EmgrEvent_t *pEvent); |
The emgrCheckEvent() function verifies that an event structure is valid.
Parameter:
| *pEvent | pointer to an event structure |
Return value:
Success: 0 (event structure is valid)
Failure:
-1 The event structure is not valid.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int *emgrCloneEvent(const EmgrEvent_t *pEvent); |
The emgrCloneEvent() function clones all parameters and data from an event, except the eventID, source, timestamp, and uid attributes. This function is useful for DSO consumers that must modify an event and pass it elsewhere for further processing.
Parameters:
| *pEvent | pointer to the event structure |
Return value:
Success: 0
Failure: NULL pointer (The *pEvent pointer that was passed to the function points to corrupted memory, or a memory allocation failure occurred.)
GeneralBlock_t *emgrCloneGb(const EmgrEvent_t *pGb); |
The emgrCloneGb() function clones the contents of a GeneralBlock structure.
Parameters:
| *pGb | pointer to the GeneralBlock structure |
Return value:
Success: 0
Failure: NULL pointer (The *pGB pointer that was passed to the function points to corrupted memory, or a memory allocation failure occurred.)
int emgrForwardEvent(EmgrEvent_t *pEvent,
const char *forwardPath);
|
The emgrForwardEvent() function specifies that the Event Manager should forward an event to one or more remote hosts; this function uses the emgrSendEvent() function to forward the event to the first host in the forward path.
Parameters:
| *pEvent | pointer to the event structure | |
| *forwardPath | pointer to a character string The character string contains the path of hosts that should receive an event and has the following format: hostname1[:port]>hostname2>[:port]>...hostnameN[:port] Example: host1.sgi.com>host2.sgi.com:5553>host3.sgi.com |
Return value:
Success: 0
Failure:
-1 The forward path is invalid or there is a communication error with the first host in the path.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrFreeEvent(EmgrEvent_t *pEvent); |
The emgrFreeEvent() function frees up all memory resources allocated to an event.
Parameters:
| *pEvent | pointer to an event structure |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
const void *emgrGetEventItem(const EmgrEvent_t *pEvent,
const char *name,
int *pType,
int *pLength);
|
This emgrGetEventItem() function returns the value of an item.
Parameters:
| *pEvent | pointer to the event structure | |
| *name | pointer to a character string that contains the name of the requested item | |
| *pType | pointer to an integer that holds the type of data that the function retrieves The integer can have the following values: 1 = file data 2 = binary data 3 = string data | |
| *pLength | pointer to an integer that holds the length of the data that the function retrieves (the length of the string if the function returns a string, the length of the binary large object (BLOB) of data if the function returns binary data, or the file length if the function returns a file) |
Return value:
Success: Pointer to a character array if the item is a string, pointer to a binary array if the item is binary data, or pointer to a GbFileValue structure (type GbFileValue_t) if the item is a file
Failure: NULL pointer
const struct GeneralBlock *emgrGetFirstEventGb(EmgrEvent_t *pEvent); |
The emgrGetFirstEventGb() function returns the first GeneralBlock structure that is attached to an event and initializes an iterator to use with the emgrGetNextEventGb() function.
Parameters:
| *pEvent | pointer to the event structure |
Return value:
Success: Pointer to the GeneralBlock structure
Failure: NULL pointer
int emgrGetFirstEventItem(EmgrEvent_t *pEvent,
const char **pName,
const void **pValue,
int *pType,
int *pLength);
|
The emgrGetFirstEventItem() function traverses event data and returns the first item and value of the event data initialized into pName and pValue. It initializes the iterator.
Parameters:
| *pEvent | pointer to the event structure | |
| **pName | pointer to the location where the returned item name pointer is stored | |
| **pValue | pointer to a character array if the item is a string, pointer to a binary array if the item is binary data, or pointer to a GbFileValue structure (type GbFileValue_t) if the item is a file | |
| *pType | pointer to an integer that holds the type of data that the function retrieves The integer can have the following values: 1 = file data 2 = binary data 3 = string data | |
| *pLength | pointer to an integer that holds the length of the data that the function retrieves (the length of the string if the function returns a string, the length of the BLOB of data if the function returns binary data, or the file length if the function returns a file) |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
const struct GeneralBlock *emgrGetNextEventGb(EmgrEvent_t *pEvent); |
The emgrGetFirstEventGb() function returns the next GeneralBlock structure that is attached to an event.
Parameters:
| *pEvent | pointer to the event structure |
Return value:
Success: Pointer to the GeneralBlock structure
Failure: NULL pointer
int emgrGetNextEventItem(EmgrEvent_t *pEvent,
const char **pName,
const void **pValue,
int *pType,
int *pLength);
|
The emgrGetNextEventItem() function traverses the event data and returns the item and value of the next item in the event data to pName and pValue.
Parameters:
| *pEvent | pointer to the event structure | |
| **pName | pointer to the location where the returned item name pointer is stored | |
| **pValue | pointer to a character array if the item is a string, pointer to a binary array if the item is binary data, or pointer to a GbFileValue structure (type GbFileValue_t) if the item is a file | |
| *pType | pointer to an integer that holds the type of data that the function retrieves The integer can have the following values: 1 = file data 2 = binary data 3 = string data | |
| *pLength | pointer to an integer that holds the length of the data that the function retrieves (the length of the string if the function returns a string, the length of the BLOB of data if the function returns binary data, or the file length if the function returns a file) |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrIsDaemonInstalled(); |
The emgrIsDaemonInstalled() function identifies whether the Event Manager server is installed on the local system.
Parameters: none
Return value:
0: Event Manager server is installed
1: Event Manager server is not installed
Note: This function works only with the default configuration. If you modify how the Event Manager is configured or installed, this function fails.
int emgrIsDaemonStarted(const char *server); |
The emgrIsDaemonStarted() function identifies whether the Event Manager daemon is running on the specified system.
Parameters:
| *server | pointer to a character string that contains the name of the server to check |
Return value:
0: Event Manager daemon is running on the specified system
1: Event Manager daemon is not running on the specified system
Note: This function works only with the default configuration. If you modify how the Event Manager is configured or installed, this function fails.
EmgrEvent_t *emgrNewQuery(const char *appname,
int evClass,
int evType,
const char *source,
const char *origin);
|
The emgrNewQuery() function is a wrapper to the emgrAllocEvent() function. The emgrNewQuery() function allocates an event structure and initializes the event header to conduct a query of events that are currently subscribed.
Parameters:
| *appname | pointer to a character string that contains the name of the application that owns the event (has domain over the event class and type) Set this parameter to the NULL character pointer to specify any application | |
| evClass | event class to match (Set this parameter to -1 to select all classes.) | |
| evType | event type to match (Set this parameter to -1 to select all event types.) | |
| *source | pointer to a character string that contains the name of the host or hosts from which to query events (If the string contains more than one host, separate the hosts with spaces and/or commas. If the string is empty or NULL, events from any source are used.) | |
| *origin | pointer to a character string that contains the name of the application that logs the event. If the string is empty or NULL, events from any origin are used |
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
EmgrEvent_t *emgrNewSubscribe(const char *appname,
int evClass,
int evType,
const char *source,
const char *origin);
|
The emgrNewSubscribe() function is a wrapper to the emgrAllocEvent() function. The emgrNewSubscribe() function allocates an event structure and initializes the event header with the specified data.
Parameters:
| *appname | pointer to a character string that contains the name of the application that owns the event (has domain over the event class and type) (Set this string to NULL to select events from any application.) | |
| evClass | event class to subscribe (Set this parameter to -1 to select all classes.) | |
| evType | event type to subscribe (Set this parameter to -1 to select all event types.) | |
| *source | pointer to a character string that contains the name of the host or hosts from which to subscribe events (If the string contains more than one host, separate the hosts with spaces and/or commas. If the string is empty or NULL, events from any source are used.) | |
| *origin | pointer to a character string that contains the name of the application that logs the event (If the application that sends the events also owns the events, set the origin and appname parameters to the same value. Set this parameter to empty string or the NULL character pointer to specify any origin.) |
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
EmgrEvent_t *emgrNewUnSubscribe(const char *appname,
int evClass,
int evType,
const char *source,
const char *origin);
|
The emgrNewUnSubscribe() function is a wrapper to the emgrAllocEvent() function. The emgrNewUnSubscribe() function allocates an event structure and initializes the event header for unsubscription using the data provided.
Parameters:
| *appname | pointer to a character string that contains the name of the application that owns the event (has domain over the event class and type)
| |||
| evClass | event class to subscribe (Set this parameter to -1 to select all classes.) | |||
| evType | event type to subscribe (Set this parameter to -1 to select all event types.) | |||
| *source | pointer to a character string that contains the name of the host or hosts from which to subscribe events (If the string contains more than one host, separate the hosts with spaces and/or commas. If the string is empty or NULL, events are unsubscribed from any host.) | |||
| *origin | pointer to a character string that contains the name of the application that logs the event (If the application that sends the events also owns the events, set the origin and appname parameters to the same value. Set this parameter to empty string or the NULL character pointer to specify any host.)
|
Return value:
Success: Pointer to the event structure
Failure: NULL pointer
void emgrPrintEvent(const EmgrEvent_t *pEvent,
FILE *out);
|
The emgrPrintEvent() function prints an event to a FILE stream.
Parameters:
| *pEvent | pointer to the event structure | |
| *out | pointer to the FILE stream |
Return value: None
int emgrRunQuery(EmgrEvent_t *pQueryEvent,
const char *host,
EmgrEvent_t ***ppRetEvents,
int *pEvCount,
int timeout);
|
The emgrRunQuery() function executes a subscription query.
Parameters:
| *appname | pointer returned by the emgrNewQuery() function | |||
| *host | hostname (and optionally port number) of the system to query | |||
| evType | event type to match (Set this parameter to -1 to select all event types.) | |||
| ***ppRetEvents | array of pointers to events that match the query | |||
| *pEvCount | number of returned events
| |||
| timeout | number of seconds to wait for a return from the Event Manager |
Return value:
Success: 0 (with ppRetEvents and pEvCount set to values)
Failure:
-1 An unspecified error occurred.
4 The *pQueryEvent pointer that was passed to the function points to corrupted memory.
int emgrRunSubscribe(EmgrEvent_t *pSubscrEvent,
const char *host,
int timeout,
char **pRetEventMask);
|
The emgrRunSubscribe() function adds subscription attributes to an event (Use this function instead of the emgrSendEvent() function if operation completion status is needed.) This function can subscribe multiple events at a time.
Parameters:
| *pSubscrEvent | pointer to the event structure | |
| *host | pointer to a character string that contains the hostname | |
| timeout | number of seconds to wait for a return from the Event Manager | |
| **pRetEventMask | address of a variable that returns the subscription status (each element contains `0' plus the subscription status) |
Return value:
Success: 0 (with pRetEventMask set to a value)
Failure:
-1 An unspecified error occurred.
4 The *pSubscrEvent pointer that was passed to the function points to corrupted memory.
int emgrRunUnSubscribe(EmgrEvent_t *pSubscrEvent,
const char *host,
int timeout,
char **pRetEventMask);
|
The emgrRunUnSubscribe() function unsubscribes events. (Use this function instead of the emgrSendEvent() function if operation completion status is needed.) This function can unsubscribe multiple events at a time.
Parameters:
| *pSubscrEvent | pointer to the event structure | |
| *host | pointer to a character string that contains the hostname | |
| timeout | number of seconds to wait for a return from the Event Manager | |
| **pRetEventMask | address of a variable that returns the subscription status (each element contains `0' plus the subscription status) |
Return value:
Success: 0 (with pRetEventMask set to a value)
Failure:
-1 An unspecified error occurred.
4 The *pSubscrEvent pointer that was passed to the function points to corrupted memory.
const struct GeneralBlock *emgrSearchGb(EmgrEvent_t *pEvent,
const char *tag);
|
The emgrSearchGb() function locates the GeneralBlock referenced by a tag that you specify.
Parameters:
| *pEvent | pointer to the event structure | |
| *tag | pointer to a character string that contains the tag for the GeneralBlock that you want to locate |
Return value:
Success: Pointer to the GeneralBlock structure
Failure: NULL pointer
int *emgrSendEvent(EmgrEvent_t *pEvent,
const char *host);
|
The emgrSendEvent() sends an event to the Event Manager on the specified host.
Parameters:
| *pEvent | pointer to the event structure | |
| *host | pointer to a character string that contains the hostname of the Event Manager used to subscribe events. The character string uses the following format: <hostname>[:<port_number>] If you specify NULL or an empty string, the function subscribes the event with the Event Manager on the local system. |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSetToForward(EmgrEvent_t *pEvent,
const char *forwardPath);
|
The emgrSetToForward() function specifies that the Event Manager should forward an event to one or more remote hosts.
Parameters:
| *pEvent | pointer to the event structure | |
| *forwardPath | pointer to a character string The character string contains the path of hosts that should receive an event and has the following format: hostname1[:port]>hostname2>[:port]>...hostnameN[:port] Example: host1.sgi.com>host2.sgi.com:5553>host3.sgi.com |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
EmgrEvent_t *emgrShmCliInitEvent(int argc,
const char *argv[],
int *pError);
|
The emgrShmCliInitEvent() function is a wrapper to the emgrShmInitEvent() function. It hides the details and simplifies command-line option parsing to main(), searches for a shared memory option, and calls the emgrShmInitEvent() function.
Parameters:
| argc | number of arguments | |
| *argv[] | pointer to the array of arguments | |
| *pError | pointer to the error code when an error occurs |
Return value:
Success: Pointer to the initialized event structure
Failure: NULL pointer (*pError points to the error code.)
EmgrEvent_t *emgrShmInitEvent(int shmId,
int *pError);
|
The emgrShmInitEvent() function initializes an event from shared memory that the Event Manager allocated.
Parameters:
| shmId | shared memory ID (that was passed to the consumer process as a command-line parameter) | |
| *pError | pointer to the error code when an error occurs |
Return value:
Success: Pointer to the initialized event structure
Failure: NULL pointer (*pError points to the error code.)
The error is the system error number from the errNO global variable. (Refer to the /usr/include/errno.h and /usr/include/linux/errno.h files for more information.)
int emgrSubscribeSpecCntFreq(EmgrEvent_t *pEvent,
int freq);
|
The emgrSubscribeSpecCntFreq() function is a wrapper to the emgrAddItemToEvent() function. The emgrSubscribeSpecCntFreq() function adds a tagged item to a subscription event to specify how often the Event Manager should send a matching event to a matching subscriber.
Parameters:
| *pEvent | pointer to the event structure | |
| freq | count frequency value (The Event Manager sends one of this number of events to the subscriber; for example, if you set freq to 5, the Event Manager sends every fifth matching event to the subscriber.) |
Return value:
Success: 0
Failure:
-1 A memory allocation failure occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecDsoConsumer(EmgrEvent_t *pEvent,
const char *dsoPath,
const char *callName,
const char *prmSpec);
|
The emgrSubscribeSpecDsoConsumer() function subscribes events from consumers that are implemented as dynamic shared object (DSO) libraries that are called from the Event Manager server.
Parameters:
| *pEvent | pointer to the event structure | |
| *dsoPath | pointer to a character string that contains the pathname of the consumer DSO library | |
| *callName | pointer to a character string that contains the name of the main consumer function to call | |
| *prmSpec | pointer to a character string of parameters for the consumer |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecExecConsumer(EmgrEvent_t *pEvent,
const char *execPath,
const char *prmSpec);
|
The emgrSubscribeSpecExecConsumer() function subscribes events from applications that are launched with the fork() and exec() commands. Event parameters are passed to the consumer on the command line.
Parameters:
| *pEvent | pointer to the event structure | |
| *execPath | pointer to a character string that contains the pathname of the consumer application to launch | |
| *prmSpec | pointer to a string of parameters for the application |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecExecShMemConsumer(EmgrEvent_t *pEvent,
const char *execPath,
const char *prmSpec);
|
The emgrSubscribeSpecExecShMemConsumer() function subscribes events from consumer applications that are launched via fork() and exec() commands. Event parameters are passed to the consumer applications via shared memory handoffs handled by the API layer.
Parameters:
| *pEvent | pointer to the event structure | |
| *execPath | pointer to a character string that contains the pathname of the consumer application to launch | |
| *prmSpec | pointer to a string of parameters for the application |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecFacility(EmgrEvent_t *pEvent,
int facility);
|
The emgrSubscribeSpecFacility() function is a wrapper to the emgrAddItemToEvent() function. The emgrSubscribeSpecFacility() function adds a tagged item to a subscription or unsubscription event to specify an optional event facility filter (used for subscription matching).
Parameters:
| *pEvent | pointer to the event structure | |
| facility | facility ID value (same as syslog facility value) |
Return value:
Success: 0
Failure:
-1 A memory allocation failure occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecForwardConsumer(EmgrEvent_t *pEvent,
const char *forwardPath);
|
The emgrSubscribeSpecForwardConsumer() function specifies that the Event Manager should forward an event to another host for processing.
Parameters:
| *pEvent | pointer to the event structure | |
| *forwardPath | pointer to a character string The character string contains the path of hosts that should receive an event and has the following format: hostname1[:port]>hostname2>[:port]>...hostnameN[:port] Example: host1.sgi.com>host2.sgi.com:5553>host3.sgi.com |
Return value:
Success: 0
Failure:
-1 An unspecified error occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecPriority(EmgrEvent_t *pEvent,
int pri);
|
The emgrSubscribeSpecPriority() function is a wrapper to the emgrAddItemToEvent() function. The emgrSubscribeSpecPriority() function adds a tagged item to a subscription or unsubscription event to specify an optional event priority filter for subscription matching.
Parameters:
| *pEvent | pointer to the event structure | |
| pri | priority value (same as syslog priority value) |
Return value:
Success: 0
Failure:
| -1 | A memory allocation failure occurred. | |
| 4 | The *pEvent pointer that was passed to the function points to corrupted memory. |
int emgrSubscribeSpecRegexpMap(EmgrEvent_t *pEvent,
const char *regExp,
int evMapClass,
int evMapType);
|
The emgrSubscribeSpecRegexpMap() function is a wrapper to the emgrAddItemToEvent() function. The emgrSubscribeSpecRegexpMap() function adds a tagged item to a subscription event to specify an optional untagged event's class and type mapping before forwarding it to a subscribed consumer.
Parameters:
| *pEvent | pointer to the event structure | |
| *regExp | regular expression to compare to an event's message body | |
| evMapClass | class ID to add to the event | |
| evMapType | type ID to add to the event |
Return value:
Success: 0
Failure:
-1 A memory allocation failure occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
int emgrSubscribeSpecTimeFreq(EmgrEvent_t *pEvent,
int freq);
|
The emgrSubscribeSpecTimeFreq() function is a wrapper to the emgrAddItemToEvent() function. The emgrSubscribeSpecTimeFreq() function adds a tagged item to a subscription event that specifies how often (in events/second) a matching event should be sent to a subscribed consumer. This function enables you to limit (or throttle) the number of events that are sent to a consumer each second.
The Event Manager divides the actual number of events that it receives in a second by the frequency value (freq) and rounds the value down to the nearest integer value; the Event Manager sends the resulting number of events to the subscribed consumer each second. Table 2-3 shows the number of events that are sent to a consumer for various example frequency (freq) values.
Table 2-4. Event Frequency Examples
Number of Events
Received by the Event
Manager (Per Second) | Number of Events Sent to Subscribed Consumer (Per Second) freq = 1 | freq = 2 | freq = 3 | freq = 4 | freq = 5 |
|---|---|---|---|---|---|
0 | 0 | 0 | 0 | 0 | 0 |
1 | 1 | 0 | 0 | 0 | 0 |
2 | 2 | 1 | 0 | 0 | 0 |
3 | 3 | 1 | 1 | 0 | 0 |
4 | 4 | 2 | 1 | 1 | 0 |
5 | 5 | 2 | 1 | 1 | 1 |
6 | 6 | 3 | 2 | 1 | 1 |
7 | 7 | 3 | 2 | 1 | 1 |
8 | 8 | 4 | 2 | 2 | 1 |
9 | 9 | 4 | 3 | 2 | 1 |
10 | 10 | 5 | 3 | 2 | 2 |
11 | 11 | 5 | 3 | 2 | 2 |
12 | 12 | 6 | 4 | 3 | 2 |
13 | 13 | 6 | 4 | 3 | 2 |
14 | 14 | 7 | 4 | 3 | 2 |
15 | 15 | 7 | 5 | 3 | 3 |
16 | 16 | 8 | 5 | 4 | 3 |
17 | 17 | 8 | 5 | 4 | 3 |
18 | 18 | 9 | 6 | 4 | 3 |
19 | 19 | 9 | 6 | 4 | 3 |
20 | 20 | 10 | 6 | 5 | 4 |
Parameters:
| *pEvent | pointer to the event structure | |
| freq | frequency value |
Return value:
Success: 0
Failure:
-1 A memory allocation failure occurred.
4 The *pEvent pointer that was passed to the function points to corrupted memory.
typedef void *SearchMarker_t;
SearchMarker_t getConfigValue(const char *key,
const char **value,
SearchMarker_t from);
|
The getConfigValue() function retrieves the configuration value for a specified item.
Parameters:
| *key | pointer to a character string that contains the search key | |
| **value | pointer to the location where the result string pointer is stored | |
| from | token that specifies where the function should begin its search (Set this parameter to NULL for the first getConfigValue() function call and set it to the return value from the previous getConfigValue() function call to continue searching from the point where the previous search ended.) |
Return value:
Success: A token that indicates the location to begin the search the next time that the function is called.
Failure: None