LIBPFM(3)                 Linux Programmer's Manual                LIBPFM(3)

NAME         top

       pfm_find_event - search for an event masks

SYNOPSIS         top

       #include <perfmon/pfmlib.h>

       int pfm_find_event(const char *str);

DESCRIPTION         top

       This function is used to convert an event string passed in str into
       an opaque event identifier, i.e., the return value.

       Events are first manipulated a strings which contain the event name,
       sub-event names and optional filters and modifiers. This function
       analyzes the string and try to find the matching event.

       The event string is a structured string and it is composed as


       The various components are separated by : or ::, they are defined as

              This is an optional prefix to designate a specific PMU model.
              With the prefix the event which matches the event_name is
              used. In case multiple PMU models are activated, there may be
              conflict with identical event names to mean the same or
              different things. In that case, it is necessary to fully
              specify the event with a pmu_name. That string corresponds to
              what is returned by pfm_get_pmu_name().

              This is the event name and is required. The library is not
              case sensitive on event string. The event name must match
              completely the actual event name; it cannot be a substring.

              The optional unit mask which can be considered like a sub-
              event of the major event. If a event has unit masks, and there
              is no default, then at least one unit mask must be passed in
              the string. Multiple unit masks may be specified for a single

              A modifier is an optional filter which is provided by the
              hardware register hosting the event or by the underlying
              kernel infrastructure.  Typical modifiers include privilege
              level filters. Some modifiers are simple boolean, in which
              case just passing their names is equivalent to setting their
              value to true. Other modifiers need a specific value, in which
              case it is provided after the equal sign. No space is tolerate
              around the equal sign. The list of modifiers depends on the
              host PMU and underlying kernel API. They are documented in
              PMU-specific documentation. Multiple modifiers may be passed.
              There is not order between unit masks and modifiers.

       The library uses the generic term attribute to designate both unit
       masks and modifiers.

       Here are a few examples of event strings:

              Event RETIRED_INSTRUCTION on AMD64 processor, measure at user
              privilege level only

              Event RS_UOPS_DISPATCHED measured at user privilege level
              only, and with counter-mask set to 1

       For the purpose of this function, only the pmu_name and event_name
       are considered, everything else is parsed, thus must be valid, but is

       The function searches only for one event per call. As a convenience,
       the function will identify the event up to the first comma. In other
       words, if str is equal to "EVENTA,EVENTB", then the function will
       only look at EVENTA and will not return an error because of invalid
       event string. This is handy when parsing constant event strings
       containing multiple, comma-separated, events.

RETURN         top

       The function returns the opaque event identifier that corresponds
       that the event string. In case of error, a negative error code is
       returned instead.

ERRORS         top

              The library has not been initialized properly.

              The event string is NULL.

              The library ran out of memory.

              The event was not found

              Invalid event attribute

              Invalid event attribute value

              Too many event attributes passed

AUTHOR         top

       Stephane Eranian <>

COLOPHON         top

       This page is part of the perfmon2 (a performance monitoring library)
       project.  Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this
       manual page, send it to  This
       page was obtained from the project's upstream Git repository
       ⟨git:// perfmon2-libpfm4⟩ on
       2018-02-02.  (At that time, the date of the most recent commit that
       was found in the repository was 2018-01-25.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

                               September, 2009                     LIBPFM(3)