Debian Codegraph @

upstream/debian-unstable/man2/perfmonctl.2

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