CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

A new event log parser is allocated using pmclog_open. Argument fd may be a file descriptor opened for reading if the event stream is present in a file, or the constant PMCLOG_FD_NONE for an event stream present in memory. This function returns a cookie that is passed into the other functions in this API set.

Function pmclog_read returns the next available event in the event stream associated with argument cookie. Argument ev points to an event descriptor that which will contain the result of a successfully parsed event.

An event descriptor returned by pmclog_read has the following structure:
struct pmclog_ev {
enum pmclog_state pl_state; /* parser state after ’get_event()’ */
off_t pl_offset;/* byte offset in stream */
size_t pl_count; /* count of records so far */
struct timespec pl_ts; /* log entry timestamp */
enum pmclog_type pl_type; /* log entry kind */
union { /* log entry data */
struct pmclog_ev_allocate pl_a;
struct pmclog_ev_proccsw pl_c;
struct pmclog_ev_dropnotify pl_d;
struct pmclog_ev_procexit pl_e;
struct pmclog_ev_initialize pl_i;
struct pmclog_ev_pcsample pl_s;
struct pmclog_ev_pmcattach pl_t;
struct pmclog_ev_userdata pl_u;
struct pmclog_ev_procexec pl_x;
} pl_u;
};

The current state of the parser is recorded in pl_state. This field can take on the following values:

The rest of the event structure is valid only if field pl_state contains PMCLOG_OK. Field pl_offset contains the offset of the current record in the byte stream. Field pl_count contains the serial number of this event. Field pl_ts contains a timestamp with the system time when the event occurred. Field pl_type denotes the kind of the event returned in argument *ev and is one of the following:

Function pmclog_feed is used with parsers configured to parse memory based event streams. It is intended to be called when function pmclog_read indicates the need for more data by a returning PMCLOG_REQUIRE_DATA in field pl_state of its event structure argument. Argument data points to the start of a memory buffer containing fresh event data. Argument len indicates the number of data bytes available. The memory range [data, data + len] must remain valid till the next time pmclog_read returns an error. It is an error to use pmclog_feed on a parser configured to parse file data.

Function pmclog_read will return 0 in case a complete event record was successfully read, or will return -1 and will set the pl_state field of the event record to the appropriate code in case of an error.

fd = open(filename, O_RDONLY); /* open log file */
parser = pmclog_open(fd); /* initialize parser */
if (parser == NULL)
--handle an out of memory error--;

/* read and parse data */
while (pmclog_read(parser, &ev) == 0) {
assert(ev.pl_state == PMCLOG_OK);
/* process the event */
switch (ev.pl_type) {
case PMCLOG_TYPE_ALLOCATE:
--process a pmc allocation record--
break;
case PMCLOG_TYPE_PROCCSW:
--process a thread context switch record--
break;
case PMCLOG_TYPE_PCSAMPLE:
--process a PC sample--
break;
--and so on--
}
}

/* examine parser state */
switch (ev.pl_state) {
case PMCLOG_EOF:
--normal termination--
break;
case PMCLOG_ERROR:
--look at errno here--
break;
case PMCLOG_REQUIRE_DATA:
--arrange for more data to be available for parsing--
break;
default:
assert(0);
/*NOTREACHED*/
}

HISTORY