PERF_EVENT_OPEN(2) Linux Programmer’sManual PERF_EVENT_OPEN(2)
NAME
perf_event_open − set up performance monitoring
SYNOPSIS
#include <linux/perf_event.h>
#include <linux/hw_breakpoint.h>
int perf_event_open(struct perf_event_attr *attr,
pid_t pid,int cpu,int group_fd,
unsigned long flags);
Note:There is no glibc wrapper for this system call; see NOTES.
DESCRIPTION
Givenalist of parameters, perf_event_open() returns a file descriptor,for use in subsequent system calls
(read(2), mmap(2), prctl(2), fcntl(2), etc.).
Acall to perf_event_open() creates a file descriptor that allows measuring performance information. Each
file descriptor corresponds to one event that is measured; these can be grouped together to measure multiple
ev e nts simultaneously.
Events can be enabled and disabled in twoways: via ioctl(2) and via prctl(2). When an event is disabled it
does not count or generate overflows but does continue to exist and maintain its count value.
Events come in twoflavors: counting and sampled. A counting ev ent is one that is used for counting the
aggregate number of events that occur.Ingeneral, counting event results are gathered with a read(2) call.
A sampling ev e nt periodically writes measurements to a buffer that can then be accessed via mmap(2).
Arguments
The pid and cpu arguments allowspecifying which process and CPU to monitor:
pid == 0 and cpu == −1
This measures the calling process/thread on anyCPU.
pid == 0 and cpu >= 0
This measures the calling process/thread only when running on the specified CPU.
pid > 0 and cpu == −1
This measures the specified process/thread on anyCPU.
pid > 0 and cpu >= 0
This measures the specified process/thread only when running on the specified CPU.
pid == −1 and cpu >= 0
This measures all processes/threads on the specified CPU. This requires CAP_SYS_ADMIN ca-
pability or a /proc/sys/kernel/perf_event_paranoid value of less than 1.
pid == −1 and cpu == −1
This setting is invalid and will return an error.
When pid is greater than zero, permission to perform this system call is governed by a ptrace access mode
PTRACE_MODE_READ_REALCREDS check; see ptrace(2).
The group_fd argument allows event groups to be created. An event group has one event which is the
group leader.The leader is created first, with group_fd =−1. The rest of the group members are created
with subsequent perf_event_open() calls with group_fd being set to the file descriptor of the group leader.
(A single event on its own is created with group_fd =−1and is considered to be a group with only 1 mem-
ber.) An ev ent group is scheduled onto the CPU as a unit: it will be put onto the CPU only if all of the
ev e nts in the group can be put onto the CPU. This means that the values of the member events can be
meaningfully compared—added, divided (to get ratios), and so on—with each other,since theyhav e
counted events for the same set of executed instructions.
The flags argument is formed by ORing together zero or more of the following values:
Linux 2020-02-09 1
