Retrieves an error log entry using supplied criteria.
library liberrlog.a #include <sys/errlog.h> int errlog_find_first(handle, filter, result) errlog_handle_t handle; errlog_match_t *filter; errlog_entry_t *result; int errlog_find_next(handle, result) errlog_handle_t handle; errlog_entry_t *result; int errlog_find_sequence(handle, sequence, result) errlog_handle_t handle; int sequence; errlog_entry_t *result;
The errlog_find_first subroutine finds the first occurrence of the search argument specified by filter using the direction specified by the errlog_set_direction subroutine. The reverse direction is used if none was specified. In other words, by default, entries are searched starting with the most recent entry.
The errlog_match_t structure, pointed to by the filter parameter, defines a test expression or set of expressions to be applied to each errlog entry.
If the value passed in the filter parameter is null, the errlog_find_first subroutine returns the first entry in the log, and the errlog_find_next subroutine can then be used to return subsequent entries. To read all log entries in the desired direction, open the log, then issue errlog_find_next calls.
To define a basic expression, em_field must be set to the field in the errlog entry to be tested, em_op must be set to the relational operator to be applied to that field, and either em_intvalue or em_strvalue must be set to the value to test against. Basic expressions may be combined by attaching them to em_left and em_right of another errlog_match_t structure and setting em_op of that structure to a binary or unary operator. These complex expressions may then be combined with other basic or complex expressions in the same fashion to build a tree that can define a filter of arbitrary complexity.
The errlog_find_next subroutine finds the next error log entry matching the criteria specified by a previous errlog_find_first call. The search continues in the direction specified by the errlog_set_direction subroutine or the reverse direction by default.
The errlog_find_sequence subroutine returns the entry matching the specified error log sequence number, found in the el_sequence field of the errlog_entry structure.
The handle contains the handle returned by a prior call to errlog_open.
The filter parameter points to an errlog_match_t element defining the search argument, or the first of an argument tree.
The sequence parameter contains the sequence number of the entry to be retrieved.
The result parameter must point to the area to contain the returned error log entry.
Upon successful completion, the errlog_find_first, errlog_find_next, and errlog_find_sequence subroutines return 0, and the memory referenced by result contains the found entry.
The following errors may be returned:
| LE_ERR_INVARG | A parameter error was detected. |
| LE_ERR_NOMEM | Memory could not be allocated. |
| LE_ERR_IO | An i/o error occurred. |
| LE_ERR_DONE | No more entries were found. |
The code below demonstrates how to search for all errlog entries in a date range and with a class of H (hardware) or S (software).
{
extern int begintime, endtime;
errlog_match_t beginstamp, endstamp, andstamp;
errlog_match_t hardclass, softclass, orclass;
errlog_match_t andtop;
int ret;
errlog_entry_t result;
/*
* Select begin and end times
*/
beginstamp.em_op = LE_OP_GT; /* Expression 'A' */
beginstamp.em_field = LE_MATCH_TIMESTAMP;
beginstamp.em_intvalue=begintime;
endstamp.em_op = LE_OP_LT; /* Expression 'B' */
endstamp.em_field = LE_MATCH_TIMESTAMP;
endstamp.em_intvalue=endtime;
andstamp.em_op = LE_OP_AND; /* 'A' and 'B' */
andstamp.em_left = &beginstamp;
andstamp.em_right = &endstamp;
/*
* Select the classes we're interested in.
*/
hardclass.em_op = LE_OP_EQ; /* Expression 'C' */
hardclass.em_field = LE_MATCH_CLASS;
hardclass.em_strvalue = "H";
softclass.em_op = LE_OP_EQ; /* Expression 'D' */
softclass.em_field = LE_MATCH_CLASS;
softclass.em_strvalue = "S";
orclass.em_op = LE_OP_OR; /* 'C' or 'D' */
orclass.em_left = &hardclass;
orclass.em_right = &softclass;
andtop.em_op = LE_OP_AND; /* ('A' and 'B') and ('C' or 'D') */
andtop.em_left = &andstamp;
andtop.em_right = &orclass;
ret = errlog_find_first(handle, &andtop, &result);
}
The errlog_find_first function will return the first entry matching filter. Successive calls to the errlog_find_next function will return successive entries that match the filter specified in the most recent call to the errlog_find_first function. When no more matching entries are found, the errlog_find_first and errlog_find_next functions will return the value LE_ERR_DONE.
The errlog_open, errlog_close, errlog_set_direction, errlog_write, and errlog subroutines.