Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PMCLOG(3)              FreeBSD Library Functions Manual              PMCLOG(3)

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

     Performance Counters Library (libpmc, -lpmc)

     #include <pmclog.h>

     void *
     pmclog_open(int fd);

     pmclog_close(void *cookie);

     pmclog_read(void *cookie, struct pmclog_ev *ev);

     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

     An event descriptor returned by pmclog_read() has the following

     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

     PMCLOG_ERROR             An error occurred during parsing.

     PMCLOG_OK                A complete event record was read into *ev.

     PMCLOG_REQUIRE_DATA      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.

     PMCLOG_TYPE_MAPPINGCHANGE    A record describing an address space change
                                  for a process.

     PMCLOG_TYPE_PCSAMPLE         A record containing an instruction pointer

     PMCLOG_TYPE_PMCALLOCATE      A record describing a PMC allocation

     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

     PMCLOG_TYPE_PROCEXIT         A record describing the accumulated PMC
                                  reading for a process at the time of

     PMCLOG_TYPE_PROCFORK         A record describing a fork(2) by a target

     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

     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

     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--
             case PMCLOG_TYPE_PROCCSW:
                     --process a thread context switch record--
             case PMCLOG_TYPE_PCSAMPLE:
                     --process a PC sample--
             --and so on--

     /* examine parser state */
     switch (ev.pl_state) {
     case PMCLOG_EOF:
             --normal termination--
     case PMCLOG_ERROR:
             --look at errno here--
             --arrange for more data to be available for parsing--

     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 currently under development.  It first appeared in
     FreeBSD 6.0.

FreeBSD 11.0-PRERELEASE          June 1, 2005          FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help