Quick Navigator

Search Site

Linux VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  - PMCLOG (3)


pmclog_open, pmclog_close, pmclog_read, pmclog_feed - parse event log data generated by hwpmc(4)


Return Values
See Also


.Lb libpmc


.In pmclog.h void * pmclog_open int fd void pmclog_close void *cookie int pmclog_read void *cookie struct pmclog_ev *ev int pmclog_feed void *cookie char *data int len


These functions provide a way for application programs to extract events from an event stream generated by hwpmc(4).

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:
PMCLOG_EOF (For file based parsers only) An end-of-file condition was encountered on the configured file descriptor.
PMCLOG_ERROR An error occurred during parsing.
PMCLOG_OK A complete event record was read into *ev.
  There was insufficient data in the event stream to assemble a complete event record. For memory based parsers, more data can be fed to the parser using function pmclog_feed. For file based parsers, function pmclog_read may be retried when data is available on the configured file descriptor.

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:
PMCLOG_TYPE_CLOSELOG A marker indicating a successful close of a log file. This record will be the last record of a log file.
PMCLOG_TYPE_DROPNOTIFY A marker indicating that hwpmc(4) had to drop data due to a resource constraint.
PMCLOG_TYPE_INITIALIZE An initialization record. This is the first record in a log file.
  A record describing an address space change for a process.
PMCLOG_TYPE_PCSAMPLE A record containing an instruction pointer sample.
  A record describing a PMC allocation operation.
PMCLOG_TYPE_PMCATTACH A record describing a PMC attach operation.
PMCLOG_TYPE_PMCDETACH A record describing a PMC detach operation.
PMCLOG_TYPE_PROCCSW A record describing a PMC reading at the time of a process context switch.
PMCLOG_TYPE_PROCEXEC A record describing an execve(2) by a target process.
PMCLOG_TYPE_PROCEXIT A record describing the accumulated PMC reading for a process at the time of _exit(2).
PMCLOG_TYPE_PROCFORK A record describing a fork(2) by a target process.
PMCLOG_TYPE_SYSEXIT A record describing a process exit, sent to processes owning system-wide sampling PMCs.
PMCLOG_TYPE_USERDATA A record containing user data.

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_close releases the internal state allocated by a prior call to pmclog_open.


Function pmclog_open will return a non- NULL value if successful or NULL otherwise.

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.

Function pmclog_feed will return 0 on success or -1 in case of failure.


A template for using the log file parsing API is shown below in pseudocode:
void *parser;                   /* cookie */
struct pmclog_ev ev;            /* parsed event */
int fd;                         /* file descriptor */

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*/ }

pmclog_close(parser);           /* cleanup */


A call to pmclog_init_parser may fail with any of the errors returned by malloc(3).

A call to pmclog_read for a file based parser may fail with any of the errors returned by read(2).


read(2), malloc(3), pmc(3), hwpmc(4), pmcstat(8)


The pmclog(3) API
.Ud It first appeared in
.Fx 6.0 .
Search for    or go to Top of page |  Section 3 |  Main Index

June 1, 2005 PMCLOG (3)

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.