---
name: "pfm_get_event_info"
section: "3"
platform: "linux"
package: "libpfm"
version: "4.14.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pfm_get_event_info"
---

# pfm\_get\_event\_info(3)

get event information

## NAME

pfm\_get\_event\_info - get event information

## SYNOPSIS

```
#include <perfmon/pfmlib.h>

int pfm_get_event_info(int idx, pfm_os_t os, pfm_event_info_t *info);

```

## DESCRIPTION

This function returns in **info** information about a specific event designated by its opaque unique identifier in **idx** for the operating system specified in **os**.

The **pfm\_event\_info\_t** structure is defined as follows:

```
typedef struct {
        const char              *name;
        const char              *desc;
        const char              *equiv;
        size_t			size;
        uint64_t                code;
        pfm_pmu_t               pmu;
        pfm_dtype_t             dtype
        int                     idx;
        int                     nattrs;
        struct {
          unsigned int is_precise:1;
          unsigned int reserved_bits:31;
        };
} pfm_event_info_t;
```

The fields of this structure are defined as follows:

- **name**

  This is the name of the event. This is a read-only string.

- **desc**

  This is the description of the event. This is a read-only string. It may contain multiple sentences.

- **equiv**

  Certain events may be just variations of actual events. They may be provided as handy shortcuts to avoid supplying a long list of attributes. For those events, this field is not NULL and contains the complete equivalent event string.

- **code**

  This is the raw event code. It should not be confused with the encoding of the event. This field represents only the event selection code, it does not include any unit mask or attribute settings.

- **pmu**

  This is the identification of the PMU model this event belongs to. It is of type **pfm\_pmu\_t**. Using this value and the **pfm\_get\_pmu\_info** function, it is possible to get PMU information.

- **dtype**

  This field returns the representation of the event data. By default, it is **PFM\_DATA\_UINT64**.

  **idx** This is the event unique opaque identifier. It is identical to the idx passed to the call and is provided for completeness.

- **nattrs**

  This is the number of attributes supported by this event. Attributes may be unit masks or modifiers. If the event has not attribute, then the value of this field is simply 0.

- **size**

  This field contains the size of the struct passed. This field is used to provide for extensibility of the struct without compromising backward compatibility. The value should be set to **sizeof(pfm\_event\_info\_t)**. If instead, a value of **0** is specified, the library assumes the struct passed is identical to the first ABI version which size is **PFM\_EVENT\_INFO\_ABI0**. Thus, if fields were added after the first ABI, they will not be set by the library. The library does check that bytes beyond what is implemented are zeroes.

- **is\_precise**

  This bitfield indicates whether or not the event support precise sampling. Precise sampling is a hardware mechanism that avoids instruction address skid when using interrupt-based sampling. When the event has umasks, this field means that at least one umask supports precise sampling. On Intel X86 processors, this indicates whether the event supports Precise Event-Based Sampling (PEBS).

- **is\_speculative**

  This bitfield indicates whether or not the event includes occurrences happening during speculative execution for both wrong and correct path. Given that this kind of event information is not always available from vendors, this field uses multiple bits. A value of **PFM\_EVENT\_INFO\_SPEC\_NA** indicates that speculation information is not available. A value of **PFM\_EVENT\_INFO\_SPEC\_TRUE** indicates that the event count during speculative execution. A value of **PFM\_EVENT\_INFO\_SPEC\_FALS** indicates that the event does not count during speculative execution.

The **pfm\_os\_t** enumeration provides the following choices:

- **PFM\_OS\_NONE**

  The returned information pertains only to what the PMU hardware exports. No operating system attributes is taken into account.

- **PFM\_OS\_PERF\_EVENT**

  The returned information includes the actual PMU hardware and the additional attributes exported by the perf\_events kernel interface. The perf\_event attributes pertain only the PMU hardware. In case perf\_events is not detected, an error is returned.

- **PFM\_OS\_PERF\_EVENT\_EXT**

  The returned information includes all of what is already provided by **PFM\_OS\_PERF\_EVENT** plus all the software attributes controlled by perf\_events, such as sampling period, precise sampling.

## RETURN

If successful, the function returns **PFM\_SUCCESS** and event information in **info**, otherwise it returns an error code.

## ERRORS

- **PFMLIB\_ERR\_NOINIT**

  Library has not been initialized properly.

- **PFMLIB\_ERR\_INVAL**

  The **idx** argument is invalid or **info** is **NULL** or **size** is not zero.

- **PFMLIB\_ERR\_NOTSUPP**

  The requested **os** is not detected or supported.

## AUTHOR

Stephane Eranian \<eranian@gmail.com\>