Diff of /docs/man3/pfm_get_event_name.3 [000000] .. [4ba6cc] Maximize Restore

  Switch to side-by-side view

--- a
+++ b/docs/man3/pfm_get_event_name.3
@@ -0,0 +1,66 @@
+.TH LIBPFM 4  "September, 2009" "" "Linux Programmer's Manual"
+.SH NAME
+pfm_get_event_name, pfm_get_event_code, pfm_get_event_desc, pfm_get_event_pmu \- get event information
+.SH SYNOPSIS
+.nf
+.B #include <perfmon/pfmlib.h>
+.sp
+.BI "const char *pfm_get_event_name(int " idx ");"
+.BI "const char *pfm_get_event_desc(int " idx ");"
+.BI "int pfm_get_event_code(int " idx ", uint64_t *"code ");"
+.BI "pfm_pmu_t pfm_get_event_pmu(int " idx ");"
+.sp
+.SH DESCRIPTION
+This set of function provides information for a given event identified
+by \fBidx\fR.
+
+
+The \fBpfm_get_event_name()\fR function returns the name of the event
+given its opaque identifier in \fBidx\fR. The returned string is read-only.
+The name of an event consist of a single work, no space.
+
+
+The \fBpfm_get_event_desc()\fR function returns the desc  of the event
+given its opaque identifier in \fBidx\fR. The returned string is read-only.
+The description provides information about what the event actually measures.
+In case the description is not available, a default message is returned.
+The description may consist of multiple sentences with punctuation signs but
+there is no carriage return.
+
+The \fBpfm_get_event_code()\fR function returns in \fBcode\fR the major event
+code for the event identified by \fBidx\fR. Depending on the PMU model,
+the actual event configuration may require multiple 32 or 64 bits
+integers. The goal of this function is to return just the event code
+portion of the full event configuration. This is useful for tools
+listing events, for instance. It should not be used to get the event
+encoding for a kernel APIs. The \fBcode\fR argument must point
+to a memory region large enough to hold a single 64-bit integer.
+
+The \fBpfm_get_event_pmu()\fR function returns the unique identifier
+of type \fBpfm_pmu_t\fR for the PMU of the event specified in \fBidx\fR.
+An event identifier can only belong to at most one PMU model.
+
+.SH RETURN
+
+Both \fBpfm_get_event_name()\fR and \fBpfm_get_event_desc()\fR functions
+return a pointer to a constant string. Attempt to modify that string may
+cause a program to crash. In case the identifier in \fBidx\fR is invalid,
+\fBNULL is returned\fR. In case the event is valid but no description is
+available, \fBpfm_get_event_desc()\fR returns "no description available".
+
+The \fBpfm_get_event_code()\fR function returns an error code or \fBPFMLIB_SUCCESS\fR
+
+The \fBpfm_get_event_pmu()\fR function returns a PMU identifier or PFM_PMU_NONE
+in case the event identifier was invalid.
+if successful.
+.SH ERRORS
+.TP
+.B PFMLIB_ERR_INVAL
+The \fBcode\fR argument is \fBNULL\fR or the event identifier is invalid.
+.TP
+.B PFM_PMU_NONE
+The \fBidx\fR argument passed to \fBpfm_get_event_pmu()\fR is invalid.
+
+.SH AUTHOR
+Stephane Eranian <eranian@gmail.com>
+.PP