Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gprofng-display-text.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "GPROFNG-DISPLAY-TEXT 1"
61 .TH GPROFNG-DISPLAY-TEXT 1 2025-07-27 binutils-2.45 "User Commands"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 gprofng\-display\-text \- Display the performance data in plain text format
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBgprofng display text\fR [\fIoption(s)\fR] [\fIcommands\fR]
71 [\-script \fIscript\-file\fR] \fIexperiment(s)\fR
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 Print a plain text version of the various displays supported by gprofng.
75 .PP
76 The input consists of one or more experiment directories. Through commands,
77 the user controls the output.
78 .PP
79 There is a rich set of commands to control the display of the data. The
80 \&\fBNOTES\fR section lists the most common ones. The gprofng user guide
81 lists all the commands supported.
82 .PP
83 Commands specified on the command line need to be prepended with the dash (\*(Aq\-\*(Aq)
84 symbol.
85 .PP
86 In this example, a function overview will be shown, followed by the source
87 code listing of function \fBmy\-func\fR, annotated with the
88 performance metrics that have been recorded during the data collection
89 and stored in experiment directory \fBmy\-exp.er\fR:
90 .PP
91 .Vb 1
92 \& $ gprofng display text \-functions \-source my\-func my\-exp.er
93 .Ve
94 .PP
95 Instead of, or in addition to, specifying these commands on the command line,
96 commands may also be included in a file called the \fIscript\-file\fR.
97 .PP
98 Note that the commands are processed and interpreted from left to right,
99 \&\fIso the order matters\fR.
100 .PP
101 If this tool is invoked without options, commands, or a script file, it
102 starts in interpreter mode. The user can then issue the commands
103 interactively. The session is terminated with the \fBexit\fR command in
104 the interpreter.
105 .SH OPTIONS
106 .IX Header "OPTIONS"
107 .IP \fB\-\-version\fR 4
108 .IX Item "--version"
109 Print the version number and exit.
110 .IP \fB\-\-help\fR 4
111 .IX Item "--help"
112 Print usage information and exit.
113 .IP "\fB\-script\fR \fIscript\-file\fR" 4
114 .IX Item "-script script-file"
115 Execute the commands stored in the script file. This feature may be combined
116 with commands specified at the command line.
117 .SH NOTES
118 .IX Header "NOTES"
119 Many commands are supported. Below, the more common ones are listed in
120 mostly alphabetical order, because sometimes it is more logical to
121 swap the order of two entries.
122 .PP
123 There are many more commands. These are documented in the user guide.
124 .ie n .IP """callers\-callees""" 4
125 .el .IP \f(CWcallers\-callees\fR 4
126 .IX Item "callers-callees"
127 In a callers\-callees panel, it is shown which function(s) call the target
128 function (the \fIcallers\fR) and what functions it is calling (the
129 \&\fIcallees\fR).
130 This command prints the callers\-callees panel for each of the functions,
131 in the order specified by the function sort metric.
132 .ie n .IP """calltree""" 4
133 .el .IP \f(CWcalltree\fR 4
134 .IX Item "calltree"
135 Display the dynamic call graph from the experiment, showing the hierarchical
136 metrics at each level.
137 .ie n .IP """compare {on | off | delta | ratio}""" 4
138 .el .IP "\f(CWcompare {on | off | delta | ratio}\fR" 4
139 .IX Item "compare {on | off | delta | ratio}"
140 By default, the results for multiple experiments are aggregated. This
141 command changes this to enable the comparison of experiments for certain
142 views (e.g. the function view). The first experiment specified is defined
143 to be the reference. The following options are supported:
144 .RS 4
145 .ie n .IP """on""" 4
146 .el .IP \f(CWon\fR 4
147 .IX Item "on"
148 For each experiment specified on the command line, print the values for
149 the metrics that have been activated for the experiment.
150 .ie n .IP """off""" 4
151 .el .IP \f(CWoff\fR 4
152 .IX Item "off"
153 Disable the comparison of experiments. This is the default.
154 .ie n .IP """delta""" 4
155 .el .IP \f(CWdelta\fR 4
156 .IX Item "delta"
157 Print the values for the reference experiment. The results for the other
158 experiments are shown as a delta relative to the reference (current\-reference).
159 .ie n .IP """ratio""" 4
160 .el .IP \f(CWratio\fR 4
161 .IX Item "ratio"
162 Print the values for the reference experiment. The results for the other
163 experiments are shown as a ratio relative to the reference (current/reference).
164 .RE
165 .RS 4
166 .RE
167 .ie n .IP """disasm \fIfunction\-name\fR""" 4
168 .el .IP "\f(CWdisasm \fR\f(CIfunction\-name\fR\f(CW\fR" 4
169 .IX Item "disasm function-name"
170 List the source code and instructions for the function specified. The
171 instructions are annotated with the metrics used.
172 .ie n .IP """fsingle \fIfunction\-name\fR [\fBn\fR]""" 4
173 .el .IP "\f(CWfsingle \fR\f(CIfunction\-name\fR\f(CW [\fR\f(CBn\fR\f(CW]\fR" 4
174 .IX Item "fsingle function-name [n]"
175 Write a summary panel for the specified function. The optional parameter
176 \&\fIn\fR is needed for those cases where several functions have the same name.
177 .ie n .IP """fsummary""" 4
178 .el .IP \f(CWfsummary\fR 4
179 .IX Item "fsummary"
180 Write a summary panel for each function in the function list.
181 .ie n .IP """functions""" 4
182 .el .IP \f(CWfunctions\fR 4
183 .IX Item "functions"
184 Display a list of all functions executed. For each function the used metrics
185 (e.g. the CPU time) are shown.
186 .ie n .IP """header""" 4
187 .el .IP \f(CWheader\fR 4
188 .IX Item "header"
189 Shows several operational characteristics of the experiment(s) specified
190 on the command line.
191 .ie n .IP """limit \fIn\fR""" 4
192 .el .IP "\f(CWlimit \fR\f(CIn\fR\f(CW\fR" 4
193 .IX Item "limit n"
194 Limit the output to \fIn\fR lines.
195 .ie n .IP """lines""" 4
196 .el .IP \f(CWlines\fR 4
197 .IX Item "lines"
198 Write a list of source lines and their metrics, ordered by the current
199 sort metric.
200 .ie n .IP """metric_list""" 4
201 .el .IP \f(CWmetric_list\fR 4
202 .IX Item "metric_list"
203 Display the currently selected metrics in the function view and a list
204 of all the metrics available for the target experiment(s).
205 .ie n .IP """metrics \fImetric\-spec\fR""" 4
206 .el .IP "\f(CWmetrics \fR\f(CImetric\-spec\fR\f(CW\fR" 4
207 .IX Item "metrics metric-spec"
208 Define the metrics to be displayed in the function and callers\-callees
209 overviews.
210 .Sp
211 The \fImetric\-spec\fR can either be the keyword \fBdefault\fR
212 to restore the default metrics selection, or a colon separated list
213 with metrics.
214 .Sp
215 A special metric is \f(CW\*(C`hwc\*(C'\fR. It automatically expands to the active
216 set of hardware event counters used in the experiment(s).
217 .Sp
218 If both instructions and clock cycles have been measured, the \f(CW\*(C`CPI\*(C'\fR
219 and \f(CW\*(C`IPC\*(C'\fR metrics can be used to see the Clockcycles Per Instruction
220 and Instructions Per Clockcyle values, respectively.
221 .Sp
222 The gprofng user guide has more details how to define metrics.
223 .ie n .IP """name {short | long | mangled}[:{soname | nosoname}]""" 4
224 .el .IP "\f(CWname {short | long | mangled}[:{soname | nosoname}]\fR" 4
225 .IX Item "name {short | long | mangled}[:{soname | nosoname}]"
226 Specify whether to use the short, long, or mangled form of function names.
227 Optionally, the load object that the function is part of can be included in
228 the output by adding the \fIsoname\fR keyword. It can also be ommitted
229 (\fInosoname\fR), which is the default.
230 .Sp
231 Whether there is an actual difference between these types of names depends
232 on the language.
233 .Sp
234 Note that there should be no (white)space to the left and right of the
235 colon (\fB:\fR).
236 .Sp
237 This option should not be confused with the keyword \fBname\fR in a
238 metric definition, which is used to specify that the names of functions
239 should be shown in the function overview.
240 .ie n .IP """overview""" 4
241 .el .IP \f(CWoverview\fR 4
242 .IX Item "overview"
243 Shows a summary of the recorded performance data for the experiment(s)
244 specified on the command line.
245 .ie n .IP """pcs""" 4
246 .el .IP \f(CWpcs\fR 4
247 .IX Item "pcs"
248 Write a list of program counters (PCs) and their metrics, ordered by
249 the current sort metric.
250 .ie n .IP """sort \fImetric\-spec\fR""" 4
251 .el .IP "\f(CWsort \fR\f(CImetric\-spec\fR\f(CW\fR" 4
252 .IX Item "sort metric-spec"
253 Sort the function list on the \fImetric\-spec\fR given.
254 .Sp
255 \&\f(CW@IndexSubentry\fR{Sort, Reverse order}
256 The data can be sorted in reverse order by prepending the metric definition
257 with a minus (\fB\-\fR) sign.
258 .Sp
259 For example \fBsort \-e.totalcpu\fR.
260 .Sp
261 \&\f(CW@IndexSubentry\fR{Sort, Reset to default}
262 A default metric for the sort operation has been defined and since this is
263 a persistent command, this default can be restored with \f(CW\*(C`default\*(C'\fR as
264 the key (\fBsort default\fR).
265 .ie n .IP """source \fIfunction\-name\fR""" 4
266 .el .IP "\f(CWsource \fR\f(CIfunction\-name\fR\f(CW\fR" 4
267 .IX Item "source function-name"
268 List the source code for the function specified, annotated with the metrics
269 used.
270 .ie n .IP """viewmode {user | expert | machine}""" 4
271 .el .IP "\f(CWviewmode {user | expert | machine}\fR" 4
272 .IX Item "viewmode {user | expert | machine}"
273 This command is only relevant for Java programs. For all other languages
274 supported, the viewmode setting has no effect.
275 .Sp
276 The following options are supported:
277 .RS 4
278 .ie n .IP """user""" 4
279 .el .IP \f(CWuser\fR 4
280 .IX Item "user"
281 Show the Java call stacks for Java threads, but do not show housekeeping
282 threads. The function view includes a function called \fB<JVM\-System>\fR.
283 This represents the aggregated time from non\-Java threads.
284 In case the JVM software does not report a Java call stack, time is reported
285 against the function \fB<no Java callstack recorded>\fR.
286 .ie n .IP """expert""" 4
287 .el .IP \f(CWexpert\fR 4
288 .IX Item "expert"
289 Show the Java call stacks for Java threads when the user Java code is executed,
290 and machine call stacks when JVM code is executed, or when the JVM software
291 does not report a Java call stack. Show the machine call stacks for
292 housekeeping threads.
293 .ie n .IP """machine""" 4
294 .el .IP \f(CWmachine\fR 4
295 .IX Item "machine"
296 Show the actual native call stacks for all threads. This is the view mode
297 for C, C++, and Fortran.
298 .RE
299 .RS 4
300 .RE
301 .SH "SEE ALSO"
302 .IX Header "SEE ALSO"
303 \&\fBgprofng\fR\|(1),
304 \&\fBgprofng\-archive\fR\|(1),
305 \&\fBgprofng\-collect\-app\fR\|(1),
306 \&\fBgprofng\-display\-html\fR\|(1),
307 \&\fBgprofng\-display\-src\fR\|(1)
308 .PP
309 The user guide for gprofng is maintained as a Texinfo manual. If the
310 \&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the
311 command \fBinfo gprofng\fR should give access to this document.
312 .SH COPYRIGHT
313 .IX Header "COPYRIGHT"
314 Copyright (c) 2022\-2025 Free Software Foundation, Inc.
315 .PP
316 Permission is granted to copy, distribute and/or modify this document
317 under the terms of the GNU Free Documentation License, Version 1.3
318 or any later version published by the Free Software Foundation;
319 with no Invariant Sections, with no Front\-Cover Texts, and with no
320 Back\-Cover Texts. A copy of the license is included in the
321 section entitled "GNU Free Documentation License".