--- name: "pmclog" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/pmclog" --- # pmclog(3) parse event log data generated by hwpmc(4) ## NAME **pmclog\_open**, **pmclog\_close**, **pmclog\_read**, **pmclog\_feed** – parse event log data generated by [hwpmc(4)](/hwpmc/4.md) ## LIBRARY library “libpmc” ## SYNOPSIS **#include \** *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*); ## DESCRIPTION These functions provide a way for application programs to extract events from an event stream generated by [hwpmc(4)](/hwpmc/4.md). 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 */ union { uint64_t pl_tsc; /* TSC timestamp */ struct timespec pl_ts; /* log entry timestamp (legacy) */ }; enum pmclog_type pl_type; /* log entry kind */ union { /* log entry data */ struct pmclog_ev_callchain pl_cc; struct pmclog_ev_closelog pl_cl; struct pmclog_ev_dropnotify pl_d; struct pmclog_ev_initialize pl_i; struct pmclog_ev_map_in pl_mi; struct pmclog_ev_map_out pl_mo; struct pmclog_ev_pmcallocate pl_a; struct pmclog_ev_pmcallocatedyn pl_ad; struct pmclog_ev_pmcattach pl_t; struct pmclog_ev_pmcdetach pl_d; struct pmclog_ev_proccsw pl_c; struct pmclog_ev_procexec pl_x; struct pmclog_ev_procexit pl_e; struct pmclog_ev_procfork pl_f; struct pmclog_ev_sysexit pl_e; struct pmclog_ev_userdata pl_u; } 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*. - 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\_tsc* carries the raw CPU Time Stamp Counter (TSC) value recorded at the time of the event. This is not a wall-clock time; to convert to nanoseconds divide the TSC delta between two events by the TSC frequency (*pl\_u.pl\_i.pl\_tsc\_freq*) reported in the PMCLOG\_TYPE\_INITIALIZE record. The legacy *pl\_ts* member aliases the same storage for ABI compatibility, but its contents no longer represent a wall-clock timestamp. Note that TSC-based timestamps and *pl\_u.pl\_i.pl\_tsc\_freq* are only meaningful on x86 architectures (amd64 and i386). On all other architectures (including arm64 and powerpc), *pl\_tsc* and *pl\_u.pl\_i.pl\_tsc\_freq* are set to zero. 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)](/hwpmc/4.md) 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\_MAP\_IN A record describing the introduction of a mapping to an executable object by a [kldload(2)](/kldload/2.md) or [mmap(2)](/mmap/2.md) system call. - PMCLOG\_TYPE\_MAP\_OUT A record describing the removal of a mapping to an executable object by a [kldunload(2)](/kldunload/2.md) or [munmap(2)](/munmap/2.md) system call. - PMCLOG\_TYPE\_PCSAMPLE A record containing an instruction pointer sample. - PMCLOG\_TYPE\_PMCALLOCATE 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)](/execve/2.md) by a target process. - PMCLOG\_TYPE\_PROCEXIT A record describing the accumulated PMC reading for a process at the time of [\_exit(2)](/_exit/2.md). - PMCLOG\_TYPE\_PROCFORK A record describing a [fork(2)](/fork/2.md) 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**(). ## RETURN VALUES 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. ## EXAMPLES 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_CALLCHAIN: --process a callchain 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 */ ``` ## ERRORS A call to **pmclog\_init\_parser**() may fail with any of the errors returned by [malloc(3)](/malloc/3.md). A call to **pmclog\_read**() for a file based parser may fail with any of the errors returned by [read(2)](/read/2.md). ## SEE ALSO [read(2)](/read/2.md), [malloc(3)](/malloc/3.md), [pmc(3)](/pmc/3.md), [hwpmc(4)](/hwpmc/4.md), [pmcstat(8)](/pmcstat/8.md) ## HISTORY The **pmclog** API first appeared in FreeBSD 6.0.