.TH LIBPFM 4 "September, 2009" "" "Linux Programmer's Manual"
pfm_get_event_encoding \- get raw event encoding
.B #include <perfmon/pfmlib.h>
.BI "int pfm_get_event_encoding(const char *" str ",int *" idx ", uint64_t *"code ", int *" count ");"
This function is used to retrieve the raw event encoding corresponding to the event string in \fBstr\fR.
The string may contain unit masks and modifiers and they will be taken into account. The encoding may
take several 64-bit integers. The function can use the array passed in \fBcode\fR if the number
of entries passed in \fBcount\fR is big enough. However, if both \fBcodes\fR is \fBNULL\fR and \fBcount\fR
are 0, the function allocates the memory necessary to store the encoding. It is up to the caller to
eventually free the memory. The number of 64-bit entries used is reflected in \fB*count\fR upon
return regardless of whether the \fBcodes\fR was allocated or used as is.
The raw encoding means the encoding as mandated by the underlying PMU model. It may not be directly suitable
to pass to a kernel API. You may want to use API-specific library calls to ensure the correct encoding is passed.
If the number of 64-bit integers is greater than one, then the order in which each component is returned is
PMU-model specific. Refer to the PMU specific man page.
Here is a example of how this function could be used:
int main(int argc, char **argv)
uint64_t *codes 0;
int count = 0;
ret = pfm_initialize();
if (ret != PFMLIB_SUCCESS)
err(1", cannot initialize library %s", pfm_strerror(ret));
ret = pfm_get_event_encoding("RETIRED_INSTRUCTIONS:u", &codes, &count);
if (ret != PFM_SUCCESS)
err(1", cannot get encoding %s", pfm_strerror(ret));
for(i=0; i < count; i++)
printf("count[%d]=0x%"PRIx64"\\n", i, codes[i]);
The function returns in \fBcodes\fR the encoding of the event and in \fBcount\fR the number
of 64-bit integers to support that encoding. Upon success, \fBPFM_SUCCESS\fR is returned otherwise
a specific error code is returned.
The \fBcode\fR argument is too small for the encoding.
The \fBcode\fR or \fBcount\fR argument is \fBNULL\fR.
Not enough memory.
Event not found.
Invalid event attribute (unit mask or modifier)
Invalid modifier value.
attribute already set, cannot be changed.
Missing unit mask.
Unit masks or features cannot be combined into a single event.
Stephane Eranian <firstname.lastname@example.org>