landlock_restrict_self.2: tfix
[man-pages.git] / man2 / perfmonctl.2
blob5221df9318df77c131b7e8ef494c987d8ec0c2e3
1 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
2 .\" and Copyright (C) 2013 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" Written by Ivana Varekova <varekova@redhat.com>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH PERFMONCTL 2 2021-03-22 Linux "Linux Programmer's Manual"
8 .SH NAME
9 perfmonctl \- interface to IA-64 performance monitoring unit
10 .SH SYNOPSIS
11 .nf
12 .B #include <syscall.h>
13 .B #include <perfmon.h>
14 .PP
15 .BI "long perfmonctl(int " fd ", int " cmd ", void *" arg ", int " narg ");"
16 .fi
17 .PP
18 .IR Note :
19 There is no glibc wrapper for this system call; see NOTES.
20 .SH DESCRIPTION
21 The IA-64-specific
22 .BR perfmonctl ()
23 system call provides an interface to the
24 PMU (performance monitoring unit).
25 The PMU consists of PMD (performance monitoring data) registers and
26 PMC (performance monitoring control) registers,
27 which gather hardware statistics.
28 .PP
29 .BR perfmonctl ()
30 applies the operation
31 .I cmd
32 to the input arguments specified by
33 .IR arg .
34 The number of arguments is defined by \fInarg\fR.
35 The
36 .I fd
37 argument specifies the perfmon context to operate on.
38 .PP
39 Supported values for
40 .I cmd
41 are:
42 .TP
43 .B PFM_CREATE_CONTEXT
44 .nf
45 .BI  "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);"
46 .fi
47 Set up a context.
48 .IP
49 The
50 .I fd
51 parameter is ignored.
52 A new perfmon context is created as specified in
53 .I ctxt
54 and its file descriptor is returned in \fIctxt->ctx_fd\fR.
55 .IP
56 The file descriptor can be used in subsequent calls to
57 .BR perfmonctl ()
58 and can be used to read event notifications (type
59 .IR pfm_msg_t )
60 using
61 .BR read (2).
62 The file descriptor is pollable using
63 .BR select (2),
64 .BR poll (2),
65 and
66 .BR epoll (7).
67 .IP
68 The context can be destroyed by calling
69 .BR close (2)
70 on the file descriptor.
71 .TP
72 .B PFM_WRITE_PMCS
73 .\" pfm_write_pmcs()
74 .nf
75 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);"
76 .fi
77 Set PMC registers.
78 .TP
79 .B PFM_WRITE_PMDS
80 .nf
81 .BI  "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);"
82 .fi
83 .\" pfm_write_pmds()
84 Set PMD registers.
85 .TP
86 .B PFM_READ_PMDS
87 .\" pfm_read_pmds()
88 .nf
89 .BI  "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);"
90 .fi
91 Read PMD registers.
92 .TP
93 .B PFM_START
94 .\" pfm_start()
95 .nf
96 .\" .BI  "perfmonctl(int " fd ", PFM_START, arg, 1);
97 .BI  "perfmonctl(int " fd ", PFM_START, NULL, 0);"
98 .fi
99 Start monitoring.
101 .B PFM_STOP
102 .\" pfm_stop()
104 .BI  "perfmonctl(int " fd ", PFM_STOP, NULL, 0);"
106 Stop monitoring.
108 .B PFM_LOAD_CONTEXT
109 .\" pfm_context_load()
111 .BI  "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);"
113 Attach the context to a thread.
115 .B PFM_UNLOAD_CONTEXT
116 .\" pfm_context_unload()
118 .BI  "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);"
120 Detach the context from a thread.
122 .B PFM_RESTART
123 .\" pfm_restart()
125 .BI  "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);"
127 Restart monitoring after receiving an overflow notification.
129 .B PFM_GET_FEATURES
130 .\" pfm_get_features()
132 .BI  "perfmonctl(int " fd ", PFM_GET_FEATURES, pfarg_features_t *" arg ", 1);"
135 .B PFM_DEBUG
136 .\" pfm_debug()
138 .BI  "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0);"
141 .I val
142 is nonzero, enable debugging mode, otherwise disable.
144 .B PFM_GET_PMC_RESET_VAL
145 .\" pfm_get_pmc_reset()
147 .BI  "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t *" req  ", n);"
149 Reset PMC registers to default values.
152 .\" .TP
153 .\" .B PFM_CREATE_EVTSETS
155 .\" create or modify event sets
156 .\" .nf
157 .\" .BI  "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n);
158 .\" .fi
159 .\" .TP
160 .\" .B PFM_DELETE_EVTSETS
161 .\" delete event sets
162 .\" .nf
163 .\" .BI  "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n);
164 .\" .fi
165 .\" .TP
166 .\" .B PFM_GETINFO_EVTSETS
167 .\" get information about event sets
168 .\" .nf
169 .\" .BI  "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n);
170 .\" .fi
171 .SH RETURN VALUE
172 .BR perfmonctl ()
173 returns zero when the operation is successful.
174 On error, \-1 is returned and
175 .I errno
176 is set to indicate the error.
177 .SH VERSIONS
178 .BR perfmonctl ()
179 was added in Linux 2.4;
180 .\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7
181 it was removed in Linux 5.10.
182 .SH STANDARDS
183 .BR perfmonctl ()
184 is Linux-specific and is available only on the IA-64 architecture.
185 .SH NOTES
186 This system call was broken for many years,
187 and ultimately removed in Linux 5.10.
189 Glibc does not provide a wrapper for this system call;
190 on kernels where it exists, call it using
191 .BR syscall (2).
192 .SH SEE ALSO
193 .BR gprof (1)
195 The perfmon2 interface specification