head	1.2;
access;
symbols
	netbsd-11-0-RC6:1.1.1.1
	netbsd-11-0-RC5:1.1.1.1
	netbsd-11-0-RC4:1.1.1.1
	netbsd-11-0-RC3:1.1.1.1
	netbsd-11-0-RC2:1.1.1.1
	netbsd-11-0-RC1:1.1.1.1
	perseant-exfatfs-base-20250801:1.1.1.1
	netbsd-11:1.1.1.1.0.4
	netbsd-11-base:1.1.1.1
	perseant-exfatfs:1.1.1.1.0.2
	perseant-exfatfs-base-20240630:1.1.1.1
	binutils-2-42:1.1.1.1
	FSF:1.1.1;
locks; strict;
comment	@# @;


1.2
date	2025.08.25.15.47.39;	author christos;	state dead;
branches;
next	1.1;
commitid	83YQOH8LeFn9V78G;

1.1
date	2024.06.30.16.01.00;	author christos;	state Exp;
branches
	1.1.1.1;
next	;
commitid	Eqxmo2uubpM9w1gF;

1.1.1.1
date	2024.06.30.16.01.00;	author christos;	state Exp;
branches
	1.1.1.1.2.1;
next	;
commitid	Eqxmo2uubpM9w1gF;

1.1.1.1.2.1
date	2024.06.30.16.01.00;	author perseant;	state dead;
branches;
next	1.1.1.1.2.2;
commitid	NkoYLLCQWWw9v4gF;

1.1.1.1.2.2
date	2024.07.01.01.00.14;	author perseant;	state Exp;
branches;
next	;
commitid	NkoYLLCQWWw9v4gF;


desc
@@


1.2
log
@merge conflicts
@
text
@@@c ----------------------------------------------------------------------------
@@c This is the Texinfo source file for the gp-display-text man page.
@@c
@@c Author: Ruud van der Pas
@@c ----------------------------------------------------------------------------
@@ifset man
\input texinfo @@c -*-texinfo-*-
@@setfilename gp-display-text
@@settitle Display the performance data in plain text format
@@include gp-macros.texi
@@end ifset

@@c ----------------------------------------------------------------------------
@@c This is from the man-pages(7) man page
@@c
@@c "The list below shows conventional or suggested sections.  Most manual pages
@@c  should include at least the highlighted sections.  Arrange a new manual
@@c  page so that sections are placed in the order shown in the list."
@@c
@@c              NAME
@@c              SYNOPSIS
@@c              CONFIGURATION    [Normally only in Section 4]
@@c              DESCRIPTION
@@c              OPTIONS          [Normally only in Sections 1, 8]
@@c              EXIT STATUS      [Normally only in Sections 1, 8]
@@c              RETURN VALUE     [Normally only in Sections 2, 3]
@@c              ERRORS           [Typically only in Sections 2, 3]
@@c              ENVIRONMENT
@@c              FILES
@@c              VERSIONS         [Normally only in Sections 2, 3]
@@c              ATTRIBUTES       [Normally only in Sections 2, 3]
@@c              CONFORMING TO
@@c              NOTES
@@c              BUGS
@@c              EXAMPLES
@@c              AUTHORS          [Discouraged]
@@c              REPORTING BUGS   [Not used in man-pages]
@@c              COPYRIGHT        [Not used in man-pages]
@@c              SEE ALSO
@@c
@@c This is what the texi2pod.pl tool recognizes:
@@c
@@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@@c
@@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@@c makes sense and adhered to for the other formats.
@@c ----------------------------------------------------------------------------

@@c ----------------------------------------------------------------------------
@@c NAME section
@@c ----------------------------------------------------------------------------

@@ManPageStart{NAME}
@@c man begin NAME

gp-display-text - Display the performance data in plain text format

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c SYNOPSIS section
@@c ----------------------------------------------------------------------------

@@ManPageStart{SYNOPSIS}
@@c man begin SYNOPSIS

@@command{gprofng display text} [@@var{option(s)}] [@@var{commands}]
[-script @@var{script-file}] @@var{experiment(s)}

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c DESCRIPTION section
@@c ----------------------------------------------------------------------------

@@ManPageStart{DESCRIPTION}
@@c man begin DESCRIPTION

Print a plain text version of the various displays supported by gprofng.

The input consists of one or more experiment directories.  Through commands,
the user controls the output.

There is a rich set of commands to control the display of the data.  The
@@samp{NOTES} section lists the most common ones.  The gprofng user guide
lists all the commands supported.

Commands specified on the command line need to be prepended with the dash ('-')
symbol.

In this example, a function overview will be shown, followed by the source
code listing of function @@samp{my-func}, annotated with the
performance metrics that have been recorded during the data collection
and stored in experiment directory @@samp{my-exp.er}:

@@smallexample
$ gprofng display text -functions -source my-func my-exp.er
@@end smallexample

Instead of, or in addition to, specifying these commands on the command line,
commands may also be included in a file called the @@var{script-file}.

Note that the commands are processed and interpreted from left to right,
@@emph{so the order matters}.

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 @@command{exit} command in
the interpreter.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c OPTIONS section
@@c ----------------------------------------------------------------------------

@@ManPageStart{OPTIONS}
@@c man begin OPTIONS

@@table @@gcctabopt

@@item --version
@@ifclear man
@@IndexSubentry{Options, @@code{--version}}
@@end ifclear

Print the version number and exit.

@@item --help
@@ifclear man
@@IndexSubentry{Options, @@code{--help}}
@@end ifclear

Print usage information and exit.

@@item -script @@var{script-file}
@@ifclear man
@@IndexSubentry{Options,  @@code{-script}}
@@IndexSubentry{Commands, @@code{script}}
@@end ifclear

Execute the commands stored in the script file.  This feature may be combined
with commands specified at the command line.

@@end table

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c NOTES section
@@c ----------------------------------------------------------------------------

@@ManPageStart{NOTES}
@@c man begin 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.

@@ifset man
There are many more commands.  These are documented in the user guide.
@@end ifset

@@table @@code

@@item callers-callees
@@ifclear man
@@IndexSubentry{Options,  @@code{-callers-callees}}
@@IndexSubentry{Commands, @@code{callers-callees}}
@@end ifclear
In a callers-callees panel, it is shown which function(s) call the target
function (the @@emph{callers}) and what functions it is calling (the
@@emph{callees}).
This command prints the callers-callees panel for each of the functions,
in the order specified by the function sort metric.

@@item calltree
@@ifclear man
@@IndexSubentry{Options,  @@code{-calltree}}
@@IndexSubentry{Commands, @@code{calltree}}
@@end ifclear
Display the dynamic call graph from the experiment, showing the hierarchical
metrics at each level.

@@item compare @@{on | off | delta | ratio@@}
@@ifclear man
@@IndexSubentry{Options,  @@code{-compare}}
@@IndexSubentry{Commands, @@code{compare}}
@@end ifclear
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:

@@table @@code

@@item on
For each experiment specified on the command line, print the values for
the metrics that have been activated for the experiment.

@@item off
Disable the comparison of experiments.  This is the default.

@@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).

@@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).

@@end table

@@item disasm @@var{function-name}
@@ifclear man
@@IndexSubentry{Options,  @@code{-disasm}}
@@IndexSubentry{Commands, @@code{disasm}}
@@end ifclear
List the source code and instructions for the function specified.  The
instructions are annotated with the metrics used.

@@item fsingle @@var{function-name} [@@samp{n}]
@@ifclear man
@@IndexSubentry{Options,  @@code{-fsingle}}
@@IndexSubentry{Commands, @@code{fsingle}}
@@end ifclear
Write a summary panel for the specified function.  The optional parameter
@@var{n} is needed for those cases where several functions have the same name.

@@item fsummary
@@ifclear man
@@IndexSubentry{Options,  @@code{-fsummary}}
@@IndexSubentry{Commands, @@code{fsummary}}
@@end ifclear
Write a summary panel for each function in the function list.

@@item functions
@@ifclear man
@@IndexSubentry{Options,  @@code{-functions}}
@@IndexSubentry{Commands, @@code{functions}}
@@end ifclear
Display a list of all functions executed.  For each function the used metrics
(e.g. the CPU time) are shown.

@@item header
@@ifclear man
@@IndexSubentry{Options,  @@code{-header}}
@@IndexSubentry{Commands, @@code{header}}
@@end ifclear
Shows several operational characteristics of the experiment(s) specified
on the command line.

@@item limit @@var{n}
@@ifclear man
@@IndexSubentry{Options,  @@code{-limit}}
@@IndexSubentry{Commands, @@code{limit}}
@@end ifclear
Limit the output to @@var{n} lines.

@@item lines
@@ifclear man
@@IndexSubentry{Options,  @@code{-lines}}
@@IndexSubentry{Commands, @@code{lines}}
@@end ifclear
Write a list of source lines and their metrics, ordered by the current
sort metric.

@@item metric_list
@@ifclear man
@@IndexSubentry{Options,  @@code{-metric_list}}
@@IndexSubentry{Commands, @@code{metric_list}}
@@end ifclear
Display the currently selected metrics in the function view and a list
of all the metrics available for the target experiment(s).

@@item metrics @@var{metric-spec}
@@ifclear man
@@IndexSubentry{Options,  @@code{-metrics}}
@@IndexSubentry{Commands, @@code{metrics}}
@@end ifclear
Define the metrics to be displayed in the function and callers-callees
overviews.

The @@var{metric-spec} can either be the keyword @@samp{default}
to restore the default metrics selection, or a colon separated list
with metrics.

@@ifclear man
@@IndexSubentry{Hardware event counters, @@code{hwc} metric}
@@end ifclear
A special metric is @@code{hwc}.  It automatically expands to the active
set of hardware event counters used in the experiment(s).

@@ifclear man
@@IndexSubentry{Hardware event counters, @@code{IPC} metric}
@@IndexSubentry{Hardware event counters, @@code{CPI} metric}
@@end ifclear
If both instructions and clock cycles have been measured, the @@code{CPI}
and @@code{IPC} metrics can be used to see the Clockcycles Per Instruction
and Instructions Per Clockcyle values, respectively.

The gprofng user guide has more details how to define metrics.

@@item name @@{short | long | mangled@@}[:@@{soname | nosoname@@}]
@@ifclear man
@@IndexSubentry{Options,  @@code{-name}}
@@IndexSubentry{Commands, @@code{name}}
@@end ifclear
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 @@emph{soname} keyword.  It can also be ommitted
(@@emph{nosoname}), which is the default.

Whether there is an actual difference between these types of names depends
on the language.

Note that there should be no (white)space to the left and right of the
colon (@@samp{:}).

This option should not be confused with the keyword @@samp{name} in a
metric definition, which is used to specify that the names of functions
should be shown in the function overview.

@@item overview
@@ifclear man
@@IndexSubentry{Options,  @@code{-overview}}
@@IndexSubentry{Commands, @@code{overview}}
@@end ifclear
Shows a summary of the recorded performance data for the experiment(s)
specified on the command line.

@@item pcs
@@ifclear man
@@IndexSubentry{Options,  @@code{-pcs}}
@@IndexSubentry{Commands, @@code{pcs}}
@@end ifclear
Write a list of program counters (PCs) and their metrics, ordered by
the current sort metric.

@@item sort @@var{metric-spec}
@@ifclear man
@@IndexSubentry{Options,  @@code{-sort}}
@@IndexSubentry{Commands, @@code{sort}}
@@end ifclear
Sort the function list on the @@var{metric-spec} given.

@@IndexSubentry{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
with a minus (@@samp{-}) sign.

@@noindent
For example @@command{sort -e.totalcpu}.

@@IndexSubentry{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 @@code{default} as
the key (@@command{sort default}).

@@item source @@var{function-name}
@@ifclear man
@@IndexSubentry{Options,  @@code{-source}}
@@IndexSubentry{Commands, @@code{source}}
@@end ifclear
List the source code for the function specified, annotated with the metrics
used.

@@item viewmode @@{user | expert | machine@@}
@@ifclear man
@@IndexSubentry{Options,  @@code{-viewmode}}
@@IndexSubentry{Commands, @@code{viewmode}}
@@end ifclear
This command is only relevant for Java programs.  For all other languages
supported, the viewmode setting has no effect.

The following options are supported:

@@table @@code

@@item user
Show the Java call stacks for Java threads, but do not show housekeeping
threads.  The function view includes a function called @@samp{<JVM-System>}.
This represents the aggregated time from non-Java threads.
In case the JVM software does not report a Java call stack, time is reported
against the function @@samp{<no Java callstack recorded>}.

@@item expert
Show the Java call stacks for Java threads when the user Java code is executed,
and machine call stacks when JVM code is executed, or when the JVM software
does not report a Java call stack.  Show the machine call stacks for
housekeeping threads.

@@item machine
Show the actual native call stacks for all threads.  This is the view mode
for C, C++, and Fortran.

@@end table

@@end table

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c SEEALSO section
@@c ----------------------------------------------------------------------------

@@ManPageStart{SEE ALSO}
@@c man begin SEEALSO

gprofng(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1)

@@iftex
@@vspace{1}
@@end iftex

The user guide for gprofng is maintained as a Texinfo manual.  If the
@@command{info} and @@command{gprofng} programs are correctly installed, the
command @@command{info gprofng} should give access to this document.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c COPYRIGHT section
@@c ----------------------------------------------------------------------------

@@ManPageStart{COPYRIGHT}
@@c man begin COPYRIGHT

Copyright @@copyright{} 2022-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU 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 ``GNU Free Documentation License''.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c If this text is used for a man page, exit.  Otherwise we need to continue.
@@c ----------------------------------------------------------------------------

@@ifset man
@@bye
@@end ifset
@


1.1
log
@Initial revision
@
text
@@


1.1.1.1
log
@Import binutils-2.42 (last was 2.39)

2024-01-15  Nick Clifton  <nickc@@redhat.com>

	* 2.42 branch point.

2023-11-15  Arsen Arsenović  <arsen@@aarsen.me>

	* intl: Remove directory.  Replaced with out-of-tree GNU
	gettext.
	* .gitignore: Add '/gettext*'.
	* configure.ac (host_libs): Replace intl with gettext.
	(hbaseargs, bbaseargs, baseargs): Split baseargs into
	{h,b}baseargs.
	(skip_barg): New flag.  Skips appending current flag to
	bbaseargs.
	<library exemptions>: Exempt --with-libintl-{type,prefix} from
	target and build machine argument passing.
	* configure: Regenerate.
	* Makefile.def (host_modules): Replace intl module with gettext
	module.
	(configure-ld): Depend on configure-gettext.
	* Makefile.in: Regenerate.
	* src-release.sh: Remove references to the intl/ directory.

2023-07-03  Nick Clifton  <nickc@@redhat.com>

	2.41 Branch Point.

2023-06-26  Nick Clifton  <nickc@@redhat.com>

	* Import these updates to the config scripts

	commit 4ad4bb7c30aca1e705448ba8d51a210bbd47bb52
	Author: Paul Eggert <eggert@@cs.ucla.edu>
	Date:   Fri Jun 23 09:55:10 2023 -0700

		Quote 'like this', not `like this'.

	commit 63acb96f92473ceb5e21d873d7c0aee266b3d6d3
	Author: Paul Eggert <eggert@@cs.ucla.edu>
	Date:   Sat Jan 21 00:15:01 2023 -0600

		Fix config.sub spelling typo for "athlon"

	commit 4ce12a5c9125cedc0d0ba584444a6865396923ec
	Author: Dmitry V. Levin <ldv@@altlinux.org>
	Date:   Sun Jan 1 08:00:00 2023 +0000

		Update copyright years

	commit c397e2c040bce50bcdccb131f90115ba7e8bfc19
	Author: Arsen Arsenovi <arsen@@aarsen.me>
	Date:   Sat Sep 17 23:34:48 2022 +0200

		config.sub: add linux-mlibc targets

	commit 9f9f9b0b13197269848c76e3e057a3ed0680b4bf
	Author: Arsen Arsenovi <arsen@@aarsen.me>
	Date:   Sat Sep 17 23:34:47 2022 +0200

		config.guess: support running on Managarm systems

	commit 87e6687749da7bb2ab158a79fa83721c19ed9246
	Author: Arsen Arsenovi <arsen@@aarsen.me>
	Date:   Sat Sep 17 23:34:46 2022 +0200

		config.sub: add managarm-{mlibc,kernel} targets

	commit 20403c5701973a4cbd7e0b4bbeb627fcd424a0f1
	Author: Xiaotian Wu <wuxiaotian@@loongson.cn>
	Date:   Mon Aug 1 16:05:29 2022 +0800

		Remove loongarchx32

	commit 02ba26b218d3d3db6c56e014655faf463cefa983
	Author: Alexander von Gluck IV <kallisti5@@unixzen.com>
	Date:   Wed May 25 15:43:13 2022 -0500

		config.guess: Update Haiku guesses

	commit f56a7140386d08a531bcfd444d632b28c61a6329
	Author: Bruno Haible <bruno@@clisp.org>
	Date:   Sun May 8 19:08:08 2022 +0200

		config.guess (x86_64:Linux:*:*): Detect 32-bit ABI.

2023-04-20  Nick Clifton  <nickc@@redhat.com>

	* SECURITY.txt: New file.
	* src-release.sh (DEVO_SUPPORT): Add SECURITY.txt.

2022-12-31  Nick Clifton  <nickc@@redhat.com>

	* 2.40 binutils branch created.

2022-10-10  Nick Clifton  <nickc@@redhat.com>

	* src-release.sh: Add "-r <date>" option to create reproducible
	tarballs based upon a fixed timestamp of <date>.
	* binutils/README-how-to-make-a-release: Add a line showing how to
	use -r <date> when creating a binutils release.

2022-10-04  Nick Clifton  <nickc@@redhat.com>

	* README-maintainer-mode: Add a minimum version of dejagnu
	requirement.

2022-09-08  Nick Clifton  <nickc@@redhat.com>

	* README-maintainer-mode: Update minimum version  of gettext
	required.
@
text
@@


1.1.1.1.2.1
log
@file gp-display-text.texi was added on branch perseant-exfatfs on 2024-07-01 01:00:14 +0000
@
text
@d1 458
@


1.1.1.1.2.2
log
@Sync with HEAD.
@
text
@a0 458
@@c ----------------------------------------------------------------------------
@@c This is the Texinfo source file for the gp-display-text man page.
@@c
@@c Author: Ruud van der Pas
@@c ----------------------------------------------------------------------------
@@ifset man
\input texinfo @@c -*-texinfo-*-
@@setfilename gp-display-text
@@settitle Display the performance data in plain text format
@@include gp-macros.texi
@@end ifset

@@c ----------------------------------------------------------------------------
@@c This is from the man-pages(7) man page
@@c
@@c "The list below shows conventional or suggested sections.  Most manual pages
@@c  should include at least the highlighted sections.  Arrange a new manual
@@c  page so that sections are placed in the order shown in the list."
@@c
@@c              NAME
@@c              SYNOPSIS
@@c              CONFIGURATION    [Normally only in Section 4]
@@c              DESCRIPTION
@@c              OPTIONS          [Normally only in Sections 1, 8]
@@c              EXIT STATUS      [Normally only in Sections 1, 8]
@@c              RETURN VALUE     [Normally only in Sections 2, 3]
@@c              ERRORS           [Typically only in Sections 2, 3]
@@c              ENVIRONMENT
@@c              FILES
@@c              VERSIONS         [Normally only in Sections 2, 3]
@@c              ATTRIBUTES       [Normally only in Sections 2, 3]
@@c              CONFORMING TO
@@c              NOTES
@@c              BUGS
@@c              EXAMPLES
@@c              AUTHORS          [Discouraged]
@@c              REPORTING BUGS   [Not used in man-pages]
@@c              COPYRIGHT        [Not used in man-pages]
@@c              SEE ALSO
@@c
@@c This is what the texi2pod.pl tool recognizes:
@@c
@@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
@@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
@@c
@@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
@@c makes sense and adhered to for the other formats.
@@c ----------------------------------------------------------------------------

@@c ----------------------------------------------------------------------------
@@c NAME section
@@c ----------------------------------------------------------------------------

@@ManPageStart{NAME}
@@c man begin NAME

gp-display-text - Display the performance data in plain text format

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c SYNOPSIS section
@@c ----------------------------------------------------------------------------

@@ManPageStart{SYNOPSIS}
@@c man begin SYNOPSIS

@@command{gprofng display text} [@@var{option(s)}] [@@var{commands}]
[-script @@var{script-file}] @@var{experiment(s)}

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c DESCRIPTION section
@@c ----------------------------------------------------------------------------

@@ManPageStart{DESCRIPTION}
@@c man begin DESCRIPTION

Print a plain text version of the various displays supported by gprofng.

The input consists of one or more experiment directories.  Through commands,
the user controls the output.

There is a rich set of commands to control the display of the data.  The
@@samp{NOTES} section lists the most common ones.  The gprofng user guide
lists all the commands supported.

Commands specified on the command line need to be prepended with the dash ('-')
symbol.

In this example, a function overview will be shown, followed by the source
code listing of function @@samp{my-func}, annotated with the
performance metrics that have been recorded during the data collection
and stored in experiment directory @@samp{my-exp.er}:

@@smallexample
$ gprofng display text -functions -source my-func my-exp.er
@@end smallexample

Instead of, or in addition to, specifying these commands on the command line,
commands may also be included in a file called the @@var{script-file}.

Note that the commands are processed and interpreted from left to right,
@@emph{so the order matters}.

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 @@command{exit} command in
the interpreter.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c OPTIONS section
@@c ----------------------------------------------------------------------------

@@ManPageStart{OPTIONS}
@@c man begin OPTIONS

@@table @@gcctabopt

@@item --version
@@ifclear man
@@IndexSubentry{Options, @@code{--version}}
@@end ifclear

Print the version number and exit.

@@item --help
@@ifclear man
@@IndexSubentry{Options, @@code{--help}}
@@end ifclear

Print usage information and exit.

@@item -script @@var{script-file}
@@ifclear man
@@IndexSubentry{Options,  @@code{-script}}
@@IndexSubentry{Commands, @@code{script}}
@@end ifclear

Execute the commands stored in the script file.  This feature may be combined
with commands specified at the command line.

@@end table

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c NOTES section
@@c ----------------------------------------------------------------------------

@@ManPageStart{NOTES}
@@c man begin 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.

@@ifset man
There are many more commands.  These are documented in the user guide.
@@end ifset

@@table @@code

@@item callers-callees
@@ifclear man
@@IndexSubentry{Options,  @@code{-callers-callees}}
@@IndexSubentry{Commands, @@code{callers-callees}}
@@end ifclear
In a callers-callees panel, it is shown which function(s) call the target
function (the @@emph{callers}) and what functions it is calling (the
@@emph{callees}).
This command prints the callers-callees panel for each of the functions,
in the order specified by the function sort metric.

@@item calltree
@@ifclear man
@@IndexSubentry{Options,  @@code{-calltree}}
@@IndexSubentry{Commands, @@code{calltree}}
@@end ifclear
Display the dynamic call graph from the experiment, showing the hierarchical
metrics at each level.

@@item compare @@{on | off | delta | ratio@@}
@@ifclear man
@@IndexSubentry{Options,  @@code{-compare}}
@@IndexSubentry{Commands, @@code{compare}}
@@end ifclear
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:

@@table @@code

@@item on
For each experiment specified on the command line, print the values for
the metrics that have been activated for the experiment.

@@item off
Disable the comparison of experiments.  This is the default.

@@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).

@@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).

@@end table

@@item disasm @@var{function-name}
@@ifclear man
@@IndexSubentry{Options,  @@code{-disasm}}
@@IndexSubentry{Commands, @@code{disasm}}
@@end ifclear
List the source code and instructions for the function specified.  The
instructions are annotated with the metrics used.

@@item fsingle @@var{function-name} [@@samp{n}]
@@ifclear man
@@IndexSubentry{Options,  @@code{-fsingle}}
@@IndexSubentry{Commands, @@code{fsingle}}
@@end ifclear
Write a summary panel for the specified function.  The optional parameter
@@var{n} is needed for those cases where several functions have the same name.

@@item fsummary
@@ifclear man
@@IndexSubentry{Options,  @@code{-fsummary}}
@@IndexSubentry{Commands, @@code{fsummary}}
@@end ifclear
Write a summary panel for each function in the function list.

@@item functions
@@ifclear man
@@IndexSubentry{Options,  @@code{-functions}}
@@IndexSubentry{Commands, @@code{functions}}
@@end ifclear
Display a list of all functions executed.  For each function the used metrics
(e.g. the CPU time) are shown.

@@item header
@@ifclear man
@@IndexSubentry{Options,  @@code{-header}}
@@IndexSubentry{Commands, @@code{header}}
@@end ifclear
Shows several operational characteristics of the experiment(s) specified
on the command line.

@@item limit @@var{n}
@@ifclear man
@@IndexSubentry{Options,  @@code{-limit}}
@@IndexSubentry{Commands, @@code{limit}}
@@end ifclear
Limit the output to @@var{n} lines.

@@item lines
@@ifclear man
@@IndexSubentry{Options,  @@code{-lines}}
@@IndexSubentry{Commands, @@code{lines}}
@@end ifclear
Write a list of source lines and their metrics, ordered by the current
sort metric.

@@item metric_list
@@ifclear man
@@IndexSubentry{Options,  @@code{-metric_list}}
@@IndexSubentry{Commands, @@code{metric_list}}
@@end ifclear
Display the currently selected metrics in the function view and a list
of all the metrics available for the target experiment(s).

@@item metrics @@var{metric-spec}
@@ifclear man
@@IndexSubentry{Options,  @@code{-metrics}}
@@IndexSubentry{Commands, @@code{metrics}}
@@end ifclear
Define the metrics to be displayed in the function and callers-callees
overviews.

The @@var{metric-spec} can either be the keyword @@samp{default}
to restore the default metrics selection, or a colon separated list
with metrics.

@@ifclear man
@@IndexSubentry{Hardware event counters, @@code{hwc} metric}
@@end ifclear
A special metric is @@code{hwc}.  It automatically expands to the active
set of hardware event counters used in the experiment(s).

@@ifclear man
@@IndexSubentry{Hardware event counters, @@code{IPC} metric}
@@IndexSubentry{Hardware event counters, @@code{CPI} metric}
@@end ifclear
If both instructions and clock cycles have been measured, the @@code{CPI}
and @@code{IPC} metrics can be used to see the Clockcycles Per Instruction
and Instructions Per Clockcyle values, respectively.

The gprofng user guide has more details how to define metrics.

@@item name @@{short | long | mangled@@}[:@@{soname | nosoname@@}]
@@ifclear man
@@IndexSubentry{Options,  @@code{-name}}
@@IndexSubentry{Commands, @@code{name}}
@@end ifclear
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 @@emph{soname} keyword.  It can also be ommitted
(@@emph{nosoname}), which is the default.

Whether there is an actual difference between these types of names depends
on the language.

Note that there should be no (white)space to the left and right of the
colon (@@samp{:}).

This option should not be confused with the keyword @@samp{name} in a
metric definition, which is used to specify that the names of functions
should be shown in the function overview.

@@item overview
@@ifclear man
@@IndexSubentry{Options,  @@code{-overview}}
@@IndexSubentry{Commands, @@code{overview}}
@@end ifclear
Shows a summary of the recorded performance data for the experiment(s)
specified on the command line.

@@item pcs
@@ifclear man
@@IndexSubentry{Options,  @@code{-pcs}}
@@IndexSubentry{Commands, @@code{pcs}}
@@end ifclear
Write a list of program counters (PCs) and their metrics, ordered by
the current sort metric.

@@item sort @@var{metric-spec}
@@ifclear man
@@IndexSubentry{Options,  @@code{-sort}}
@@IndexSubentry{Commands, @@code{sort}}
@@end ifclear
Sort the function list on the @@var{metric-spec} given.

@@IndexSubentry{Sort, Reverse order}
The data can be sorted in reverse order by prepending the metric definition
with a minus (@@samp{-}) sign.

@@noindent
For example @@command{sort -e.totalcpu}.

@@IndexSubentry{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 @@code{default} as
the key (@@command{sort default}).

@@item source @@var{function-name}
@@ifclear man
@@IndexSubentry{Options,  @@code{-source}}
@@IndexSubentry{Commands, @@code{source}}
@@end ifclear
List the source code for the function specified, annotated with the metrics
used.

@@item viewmode @@{user | expert | machine@@}
@@ifclear man
@@IndexSubentry{Options,  @@code{-viewmode}}
@@IndexSubentry{Commands, @@code{viewmode}}
@@end ifclear
This command is only relevant for Java programs.  For all other languages
supported, the viewmode setting has no effect.

The following options are supported:

@@table @@code

@@item user
Show the Java call stacks for Java threads, but do not show housekeeping
threads.  The function view includes a function called @@samp{<JVM-System>}.
This represents the aggregated time from non-Java threads.
In case the JVM software does not report a Java call stack, time is reported
against the function @@samp{<no Java callstack recorded>}.

@@item expert
Show the Java call stacks for Java threads when the user Java code is executed,
and machine call stacks when JVM code is executed, or when the JVM software
does not report a Java call stack.  Show the machine call stacks for
housekeeping threads.

@@item machine
Show the actual native call stacks for all threads.  This is the view mode
for C, C++, and Fortran.

@@end table

@@end table

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c SEEALSO section
@@c ----------------------------------------------------------------------------

@@ManPageStart{SEE ALSO}
@@c man begin SEEALSO

gprofng(1),
gp-archive(1),
gp-collect-app(1),
gp-display-gui(1),
gp-display-html(1),
gp-display-src(1)

@@iftex
@@vspace{1}
@@end iftex

The user guide for gprofng is maintained as a Texinfo manual.  If the
@@command{info} and @@command{gprofng} programs are correctly installed, the
command @@command{info gprofng} should give access to this document.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c COPYRIGHT section
@@c ----------------------------------------------------------------------------

@@ManPageStart{COPYRIGHT}
@@c man begin COPYRIGHT

Copyright @@copyright{} 2022-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU 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 ``GNU Free Documentation License''.

@@c man end
@@ManPageEnd{}

@@c ----------------------------------------------------------------------------
@@c If this text is used for a man page, exit.  Otherwise we need to continue.
@@c ----------------------------------------------------------------------------

@@ifset man
@@bye
@@end ifset
@