pfm_find_event,                     pfm_find_event_byname,
       pfm_find_event_bycode, pfm_find_event_bycode_next - search
       for events


SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_find_event(char *str, int *desc);
       int pfm_find_event_byname(char *v, int *desc);
       int pfm_find_event_bycode(int code, int *desc);
       int pfm_find_event_bycode_next(int desc, int code, int *desc);


DESCRIPTION

       The  PMU  counters can be programmed to measure the number
       of occurrences of certain events.  The  number  of  events
       varies  from  one  implementation to the other. Each event
       has a name and a code which is used to program the  actual
       PMU  register. Not all event can necessarily be programmed
       on any of the available  counters  due  to  hardware  con­
       straints.

       The  library  does  not  directly expose the event code to
       user applications because it  is  not  necessary.  Instead
       applications  used names to query the library for particu­
       lar information about events. Given a  name,  the  library
       returns  an  opaque  descriptor to the applications.  Each
       descriptor is unique and has no relationship to the  event
       code.   All  functions requires the library to be properly
       initialized.

       The set of functions described here allows to get an event
       descriptor given either the name of the event or its code.
       Several events can share the same code but have  different
       names.  In the current implementation of the PMU, an event
       code is composed of a base code (called event select)  and
       a  umask. The combination of the two is guaranteed unique.
       The umask is not an architected feature and as such is not
       part of the generic interface of this library.

       The  pfm_find_event  is  a general purpose search routine.
       Given a string it returns the  descriptor  of  the  corre­
       sponding event.  The string can represent an event name or
       an event code in ASCII form.  Note that the  code  can  be
       represented in decimal or hexadecimal.

       In contrast pfm_find_event_byname will search for an event
       by interpreting the name argument as the name event  only.

       Similarly,  pfm_find_event_bycode will search for an event
       given the code argument given as an integer.

       Because there can be several events with  the  same  code,

       search for other events with the same code. Given an event
       e  and  a code, this function will look for the next event
       with the same code.  It is not necessary  to  have  called
       pfm_find_event_bycode prior to calling this function. This
       function is fully threadsafe as it does not  maintain  any
       state between calls.


RETURN

       All  functions return whether or not the call was success­
       ful.  A return value of PFMLIB_SUCCESS indicates  success,
       otherwise the value is the error code.


ERRORS

       PFMLIB_ERR_NOINIT  the  library  has  not been initialized
       properly.

       PFMLIB_ERR_INVAL
              the event descriptor is  invalid,  or  the  pointer
              argument is NULL.

       PFMLIB_ERR_NOTFOUND
              no matching event was found.


AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>


Man(1) output converted with man2html