.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "GP-DISPLAY-TEXT.1 1"
.TH GP-DISPLAY-TEXT.1 1 "2023-11-25" "binutils-2.41.50" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
gprofng display text \- Display the performance data in plain text format
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBgprofng display text\fR [\fIoption(s)\fR] [\fIcommands\fR]
[\-script \fIscript-file\fR] \fIexperiment(s)\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Print a plain text version of the various displays supported by gprofng.
.PP
The input consists of one or more experiment directories.  Through commands,
the user controls the output.
.PP
There is a rich set of commands to control the display of the data. The
\&\fB\s-1NOTES\s0\fR section lists the most common ones. The gprofng user guide
lists all the commands supported.
.PP
Commands specified on the command line need to be prepended with the dash ('\-')
symbol.
.PP
In this example, a function overview will be shown, followed by the source
code listing of function \fBmy-func\fR, annotated with the
performance metrics that have been recorded during the data collection
and stored in experiment directory \fBmy\-exp.er\fR:
.PP
.Vb 1
\&        $ gprofng display text \-functions \-source my\-func my\-exp.er
.Ve
.PP
Instead of, or in addition to, specifying these commands on the command line,
commands may also be included in a file called the \fIscript-file\fR.
.PP
Note that the commands are processed and interpreted from left to right,
\&\fIso the order matters\fR.
.PP
If this tool is invoked without options, commands, or a script file, it
starts in interpreter mode. The user can then issue the commands interactively.
The session is terminated with the \fBexit\fR command in the interpreter.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
Print the version number and exit.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Print usage information and exit.
.IP "\fB\-script\fR \fIscript-file\fR" 4
.IX Item "-script script-file"
Execute the commands stored in the script file.  This feature may be combined
with commands specified at the command line.
.SH "NOTES"
.IX Header "NOTES"
Many commands are supported. Below, the more common ones are listed in
mostly alphabetical order, because sometimes it is more logical to
swap the order of two entries.
.PP
There are many more commands. These are documented in the user guide.
.ie n .IP """callers\-callees""" 4
.el .IP "\f(CWcallers\-callees\fR" 4
.IX Item "callers-callees"
In a callers-callees panel, it is shown which function(s) call the target
function (the \fIcallers\fR) and what functions it is calling (the
\&\fIcallees\fR).
This command prints the callers-callees panel for each of the functions,
in the order specified by the function sort metric.
.ie n .IP """calltree""" 4
.el .IP "\f(CWcalltree\fR" 4
.IX Item "calltree"
Display the dynamic call graph from the experiment, showing the hierarchical
metrics at each level.
.ie n .IP """compare {on | off | delta | ratio}""" 4
.el .IP "\f(CWcompare {on | off | delta | ratio}\fR" 4
.IX Item "compare {on | off | delta | ratio}"
By default, the results for multiple experiments are aggregated. This
command changes this to enable the comparison of experiments for certain
views (e.g. the function view).  The first experiment specified is defined
to be the reference.  The following options are supported:
.RS 4
.ie n .IP """on""" 4
.el .IP "\f(CWon\fR" 4
.IX Item "on"
For each experiment specified on the command line, print the values for
the metrics that have been activated for the experiment.
.ie n .IP """off""" 4
.el .IP "\f(CWoff\fR" 4
.IX Item "off"
Disable the comparison of experiments.  This is the default.
.ie n .IP """delta""" 4
.el .IP "\f(CWdelta\fR" 4
.IX Item "delta"
Print the values for the reference experiment.  The results for the other
experiments are shown as a delta relative to the reference (current-reference).
.ie n .IP """ratio""" 4
.el .IP "\f(CWratio\fR" 4
.IX Item "ratio"
Print the values for the reference experiment.  The results for the other
experiments are shown as a ratio relative to the reference (current/reference).
.RE
.RS 4
.RE
.ie n .IP """disasm \fIfunction\-name\fP""" 4
.el .IP "\f(CWdisasm \f(CIfunction\-name\f(CW\fR" 4
.IX Item "disasm function-name"
List the source code and instructions for the function specified. The 
instructions are annotated with the metrics used.
.ie n .IP """fsingle \fIfunction\-name\fP [\fBn\fP]""" 4
.el .IP "\f(CWfsingle \f(CIfunction\-name\f(CW [\f(CBn\f(CW]\fR" 4
.IX Item "fsingle function-name [n]"
Write a summary panel for the specified function.  The optional parameter
\&\fIn\fR is needed for those cases where several functions have the same name.
.ie n .IP """fsummary""" 4
.el .IP "\f(CWfsummary\fR" 4
.IX Item "fsummary"
Write a summary panel for each function in the function list.
.ie n .IP """functions""" 4
.el .IP "\f(CWfunctions\fR" 4
.IX Item "functions"
Display a list of all functions executed.  For each function the used metrics
(e.g. the \s-1CPU\s0 time) ar shown.
.ie n .IP """header""" 4
.el .IP "\f(CWheader\fR" 4
.IX Item "header"
Shows several operational characteristics of the experiment(s) specified
on the command line.
.ie n .IP """limit \fIn\fP""" 4
.el .IP "\f(CWlimit \f(CIn\f(CW\fR" 4
.IX Item "limit n"
Limit the output to \fIn\fR lines.
.ie n .IP """lines""" 4
.el .IP "\f(CWlines\fR" 4
.IX Item "lines"
Write a list of source lines and their metrics, ordered by the current
sort metric.
.ie n .IP """metric_list""" 4
.el .IP "\f(CWmetric_list\fR" 4
.IX Item "metric_list"
Display the currently selected metrics in the function view and a list
of all the metrics available for the target experiment(s).
.ie n .IP """metrics \fImetric\-spec\fP""" 4
.el .IP "\f(CWmetrics \f(CImetric\-spec\f(CW\fR" 4
.IX Item "metrics metric-spec"
Define the metrics to be displayed in the function and callers-callees
overviews.
.Sp
The \fImetric-spec\fR can either be the keyword \fBdefault\fR
to restore the default metrics selection, or a colon separated list
with metrics.
.Sp
The gprofng user guide has more details how to define metrics.
.ie n .IP """name {short | long | mangled}[:{soname | nosoname}]""" 4
.el .IP "\f(CWname {short | long | mangled}[:{soname | nosoname}]\fR" 4
.IX Item "name {short | long | mangled}[:{soname | nosoname}]"
Specify whether to use the short, long, or mangled form of function names.
Optionally, the load object that the function is part of can be included in
the output by adding the \fIsoname\fR keyword.  It can also be ommitted
(\fInosoname\fR), which is the default.
.Sp
Whether there is an actual difference between these types of names depends
on the language.
.Sp
Note that there should be no (white)space to the left and right of the 
colon (\fB:\fR).
.ie n .IP """overview""" 4
.el .IP "\f(CWoverview\fR" 4
.IX Item "overview"
Shows a summary of the recorded performance data for the experiment(s)
specified on the command line.
.ie n .IP """pcs""" 4
.el .IP "\f(CWpcs\fR" 4
.IX Item "pcs"
Write a list of program counters (PCs) and their metrics, ordered by
the current sort metric.
.ie n .IP """sort \fImetric\-spec\fP""" 4
.el .IP "\f(CWsort \f(CImetric\-spec\f(CW\fR" 4
.IX Item "sort metric-spec"
Sort the function list on the \fImetric-spec\fR given.
.Sp
\&\f(CW@IndexSubentry\fR{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
with a minus (\fB\-\fR) sign.
.Sp
For example \fBsort \-e.totalcpu\fR.
.Sp
\&\f(CW@IndexSubentry\fR{Sort, Reset to default}
A default metric for the sort operation has been defined and since this is
a persistent command, this default can be restored with \f(CW\*(C`default\*(C'\fR as
the key (\fBsort default\fR).
.ie n .IP """source \fIfunction\-name\fP""" 4
.el .IP "\f(CWsource \f(CIfunction\-name\f(CW\fR" 4
.IX Item "source function-name"
List the source code for the function specified, annotated with the metrics
used.
.ie n .IP """viewmode {user | expert | machine}""" 4
.el .IP "\f(CWviewmode {user | expert | machine}\fR" 4
.IX Item "viewmode {user | expert | machine}"
This command is only relevant for Java programs.  For all other languages
supported, the viewmode setting has no effect.
.Sp
The following options are supported:
.RS 4
.ie n .IP """user""" 4
.el .IP "\f(CWuser\fR" 4
.IX Item "user"
Show the Java call stacks for Java threads, but do not show housekeeping
threads.  The function view includes a function called \fB<JVM\-System>\fR.
This represents the aggregated time from non-Java threads.
In case the \s-1JVM\s0 software does not report a Java call stack, time is reported
against the function \fB<no Java callstack recorded>\fR.
.ie n .IP """expert""" 4
.el .IP "\f(CWexpert\fR" 4
.IX Item "expert"
Show the Java call stacks for Java threads when the user Java code is executed,
and machine call stacks when \s-1JVM\s0 code is executed, or when the \s-1JVM\s0 software
does not report a Java call stack.  Show the machine call stacks for
housekeeping threads.
.ie n .IP """machine""" 4
.el .IP "\f(CWmachine\fR" 4
.IX Item "machine"
Show the actual native call stacks for all threads.  This is the view mode
for C, \*(C+, and Fortran.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgprofng\fR\|(1), \fBgp\-archive\fR\|(1), \fBgp\-collect\-app\fR\|(1), \fBgp\-display\-html\fR\|(1), \fBgp\-display\-src\fR\|(1)
.PP
The user guide for gprofng is maintained as a Texinfo manual.  If the
\&\fBinfo\fR and \fBgprofng\fR programs are correctly installed, the
command \fBinfo gprofng\fR should give access to this document.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2022\-2023 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".