Man Page er_print.1
NAME
er_print - print an ASCII report from Forte(TM) Developer
performance experiments
SYNOPSIS
er_print [ - | -script script | -command | -V ] experiment-list
DESCRIPTION
er_print is a utility that generates a plain text version of
the various displays supported by the Performance Analyzer.
The output is displayed on the standard output. Experiment
files are generated using the collect command, or the dbx
collector commands. The experiment-list can contain either
experiment names or experiment group names. An experiment
group is defined by a file that contains the names of the
experiments in the group. You can read experiments on des-
cendant processes either by referring to them explicitly or
by constructing an experiment group for them as described in
the collect(1) man page.
Note: You must have a license to use the Performance
Analyzer.
Based on the data collected, various metrics of performance
can be computed for functions, callers and callees, source
files, and disassembly listings. The data collected and
metrics generated are described in the collect(1) man page.
The graphical displays available are described in the
analyzer(1) man page.
OPTIONS
Option Meaning
- Enter interactive mode to read er_print com-
mands from the command line.
-script script Read er_print commands from the file script,
which contains one command per line.
-command Process the given command.
--V Display version information and exit.
The options are processed in the order they appear. Options
can be repeated. Scripts, - arguments and explicit commands
can be mixed in any order. If no command or script argu-
ments are supplied, er_print enters interactive mode to read
commands from the command line. Input from the command line
is terminated with the quit command.
COMMANDS
The commands accepted by er_print are listed below. Any
command can be abbreviated by a shorter string, as long as
the command is unambiguous.
Commands Controlling the Function List
functions
Write the function list with the current set of
metrics. The function list includes any load objects
whose functions are hidden with the object_select com-
mand.
metrics metric_list
Set the function list metrics. metric_list is a list
of metric keywords separated by colons. Each keyword
is of the form <type><visibility><metric-name>. If the
metric "name" is not in the list, it is appended to it.
<type> can be either "i" for inclusive or "e" for
exclusive. The combinations "ie" and "ei" are expanded:
for example "ie<visibility><metric-name>" is expanded
to "i<visibility><metric-name>:e<visibility><metric-
name>"
<visibility> can be any combination of "." (to show the
metric as a time), "%" (to show it as a percentage),
and "+" (to show it as a count). If the metric can
only be shown as a time or only as a count, "." and "+"
have the same meaning. For hardware counter profiling
experiments, where the counter counts in cycles, the
metric is normally shown as a time ("."); it can be
shown as a count using "+" in its <visibility> field.
The order of appearance of time, percent, and count is
fixed: it is not affected by the order of the charac-
ters in the <visibility> setting.
For example:
metrics i.%user:e.%user
means show inclusive user time and percentage, and
exclusive user time and percentage, in that order.
A list of all the available <metric-name> values for
the experiments loaded can be obtained with the
metric_list command. See the collect(1) man page for
more information on metrics.
The default metrics setting is taken from .rc files, as
described under DEFAULTS, below.
If metric-list is omitted, the current metrics setting
is printed.
If a metrics command has an error in it, it is ignored
with a warning, and the previous settings remain in
effect.
metrics default
Restores the default settings for the data recorded.
sort metric-name
Sort the function list by the given metric. The
metric-name is described under metrics. For example:
sort i.user
means to sort by inclusive user time. The <visibility>
in the metric name does not affect the sort order.
If metric-name is omitted, the current sort metric is
printed.
fsummary
Write the summary metrics panel for each function in
the function list, in the order specified by the
current sort metric. The function list includes any
load objects whose functions are hidden with the
object_select command.
fsingle function-name [N]
Write the summary metrics panel for the named function.
The optional parameter N is needed for those cases
where the function name is ambiguous; see under the
"source" command for more information. When the direc-
tive is on the command line, N is required; if it is
not needed it is ignored.
Commands Controlling the Callers-Callees List
callers-callees
Write the callers-callees panel for each function,
using the last cmetrics specification, in the order
specified by the function list sort metric (sort).
cmetrics metric-list
Set the caller-callee metrics. The metric-list is
defined in the metrics section, with the addition of
the <type> "a" for attributed.
By default, the caller-callee metrics are set to match
the function list metrics at the time the caller-callee
command is processed, and the attributed metrics are
prepended to all the visible metrics in the function
list.
If metric-list is omitted, the current caller-callee
metrics setting is printed.
csingle function-name [N]
Write the callers-callees panel for the named function.
The optional parameter N is needed for those cases
where the function name is ambiguous; see under the
"source" command for more information. When the direc-
tive is on the command-line, the N is required; if it
would not be needed it is ignored.
csort metric-name
Sort the callers and callees within the callers-callees
report for each function by the given metric. The
csort metric must be either an attributed metric, or
the address or name. By default, it is the attributed
metric corresponding to the function list sort metric
at the time the callers-callees command is processed.
If metric-name is omitted, the current callers-callees
sort metric is printed.
Commands Controlling Leak and Allocation Lists
leaks
Write the list of leaks, sorted by size, along with the
call stack for each. The entries in the leak list are
aggregated by common call stack.
allocs
Write the list of allocations, sorted by size, along
with the call stack for each. The entries in the allo-
cations list are aggregated by common call stack.
Commands Controlling Source and Disassembly Listings
source { filename | function-name } [N]
Write annotated source of the given file, or of the
file containing the given function. The optional
parameter N is needed for those cases where the
filename or function name is ambiguous; in that case
the Nth possible choice is used (with the numbering
starting from 1). If an ambiguous name is given
without the numeric specifier N, a list of choices is
printed instead of the annotated source. Each list item
contains the number that can be used for N, the name of
the object module that references the function or file,
and in the case of an ambiguous function, the function
name. If there is more than one possibility, and the N
supplied is not within the possible range, an error is
reported; if there is only one possibility, any such
error is ignored. Note that, when -source is used on
the command line, the parameter N is not optional, but
must be specified. If it would not be needed, it is
ignored.
If any compiler commentary has been selected, the com-
mentary is interleaved with the source lines in the
source listing. Lines with metrics that are equal to
or exceed a threshold percentage of the maximum for
that metric within the file have the string "##"
prepended to them, to make it easier to find the impor-
tant lines. The threshold and the classes of commen-
tary shown are governed by the source threshold set-
ting, sthresh and the preferences setting for source
compiler commentary, scc.
er_print looks for the file containing the selected
function inside the experiment. If it is not there, it
looks under the absolute pathname as recorded in the
executable. If it is not there, it tries to find a
file of the same basename in the current working direc-
tory, and use it. If you have moved the sources, or
the experiment was recorded in a different file system,
you can put a symbolic link from the current directory
to the real source location in order to see the anno-
tated source, or copy the source code and load objects
into the experiment.
src { filename | function-name } [N]
Same as source.
disasm { filename | function-name } [N]
Write annotated disassembly of the given file, or of
the file containing the given function. Ambiguities
are resolved in the same way as for the source command.
The disassembly listing has the source and any selected
compiler commentary interleaved within it, if these are
available. If the metric value on a line equals or
exceeds a threshold percentage of the maximum value of
that metric on any line in the file, the line has the
string "##" at the beginning, to make it easier to find
the important lines. The threshold is set using the
dthresh command. The classes of commentary shown are
set by the dcc command.
er_print looks for the source file for the specified
disassembly as described for the source command, and
interleaves the source with the disassembly. If the
source file can not be found, the disassembly is shown
without the source and without the compiler commetary.
scc class_list
Specify which classes of compiler commentary are shown
with annotated source. class_list is a colon separated
list of classes. Each of the classes refers to specific
types of messages. The allowed classes are:
b[asic] -- show basic messages from all classes
v[ersion] -- show version messages
w[arn] -- show warning messages
pa[rallel] -- show parallelization messages
q[uery] -- show questions from the compiler
l[oop] -- show loop transformation messages
pi[pe] -- show pipelining messages
i[nline] -- show inlining messages
m[emops] -- show messages about memory operations
f[e] -- show front-end messages
c[g] -- show code generator messages
all -- show all messages
none -- do not show messages
The classes "all" and "none" cannot be used with other
classes.
For compatibility, the threshold for flagging important
lines can be included in the list with any of the
classes, including "all" and "none".
t[hreshold]=nn
A line is flagged as important if it has a metric value
which is greater than nn percent of the largest value
of that metric on any line in the file. The default
value of nn is 75.
For example:
scc l:pi:t=50
means show loop transformation messages and pipelining
messages, and set the threshold to 50 percent.
If no scc command is given, the default setting is:
scc basic
If class_list is not specified, compiler commentary is
turned off. The scc command is normally used only in a
.er.rc file.
sthresh nn
Set the threshold for flagging important lines in the
source. A line is flagged as important if it has a
metric value which is greater than nn percent of the
largest value of that metric on any line in the file.
The default value of nn is 75.
dcc class_list
Specify which classes of compiler commentary are shown
with annotated disassembly. The class_list specifica-
tion for this command can include any of the scc
classes and the following additional specifications:
h[ex] -- show the hexadecimal representation of
each instruction
s[rc] -- interleave source in disassembly
as[rc] -- interleave annotated source, with
source-line metrics, in disassembly
If no dcc command is given, the default setting is:
dcc basic:src
This command is normally used only in a .er.rc file.
dthresh nn
Set the threshold for flagging important lines in the
disassembly. A line is flagged as important if it has
a metric value which is greater than nn percent of the
largest value of that metric on any line in the file.
The default value of nn is 75.
Commands Listing Experiments, Samples, Threads, and LWPs
exp_list
Display the list of experiments that are loaded. Each
experiment is listed with an index, which is used when
selecting samples, threads, or LWP's.
sample_list
Display the list of samples processed during the
experiment(s).
lwp_list
Display the list of LWP's processed during the
experiment(s).
thread_list
Display the list of threads processed during the
experiment(s).
Commands Controlling Selection of Experiments, Samples,
Threads, and LWPs
and
The following commands select the experiments, samples, threads,
LWPs for which data is displayed.
sample_select sample_list
sample_list is a sample list, as described below.
lwp_select lwp_list
lwp_list is a LWP list, as described below.
thread_select thread_list
thread_list is a thread list, as described below.
Each of the lists above can be a single number, a range of
numbers (n-m), a comma-separated list of numbers and ranges,
or the explicit string "all". Each list can optionally be
preceded by an experiment list with a similar format,
separated from the list by a colon (:). Multiple lists can
be concatenated, separated by a plus sign. Lists must not
contain spaces. If no experiment list is included, the list
applies to all experiments.
The experiment selection from any of the select commands is
applied to all three select targets -- threads, LWPs and
samples. For each experiment in the experiment list, if a
selection of threads, LWPs or samples exists, it is
retained; if it does not exist it is set to "all". Selec-
tions for experiments not in the experiment list are turned
off.
Some examples:
thread_select 1
selects thread 1 from all experiments.
thread_select all:1
selects thread 1 from all experiments.
thread_select all:1,3,5
selects threads 1, 3, and 5 from all experiments.
thread_select 1,2:all
selects all threads from experiments 1 and 2, as listed
by exp_list.
thread_select 1:1+2:2
selects thread 1 from experiment 1 and thread 2 from
experiment 2.
Commands Controlling Load-object Selection
object_list
List the names of available load objects. The name of
each load object is preceded by a "+" if its functions
are shown in the function list, and by a "-" if its
functions are not shown in the function list.
object_select object1,object2,...
Set the list of active load objects. The names of the
objects can be either full pathnames or the basename.
If the name contains a comma character, the name must
be surrounded by double quotes. If a load object is
selected, all of its functions that have non-zero
metrics are shown in the function list. If a load
object is not selected, its functions are not shown in
the function list, but are replaced by a single line
showing metrics for the entire load object.
By default, all load objects are selected.
Commands That List Metrics
metric_list
Display the currently selected function list metrics
and a list of metrics and keyword names that can be
used to reference them in other commands, such as sort.
The format of the metric keywords is described under
metrics. The available metrics depend on the data col-
lected. See the collect(1) man page.
cmetric_list
Display the currently selected caller-callee metrics
and a list of metrics and keyword names for the
callers-callees report. The list is displayed in the
same way as the metric_list output, except that attri-
buted metrics appear as well.
Commands Controlling the Output
outfile filename
Close any open output file, and open filename for sub-
sequent output. If filename is a minus sign (-), out-
put is written to stdout.
limit n
Limit any output to the first n entries of the report,
where n is an unsigned integer.
name { long | short }
Use long or short form of C++ function names.
Commands That Print Other Displays
header [ experiment-id ]
Write descriptive information about the specified
experiment. experiment-id is the numeric identifier of
the experiment as given by the experiment_list command.
If experiment-id is all or is omitted, the headers of
all experiments are written. Following each header,
any errors or warnings are printed. Headers for each
experiment are separated by a line of dashes.
experiment-id is required on the command line, but not
in a script or in interactive mode.
objects
List the load objects with any error or warning mes-
sages that result from the use of the load object for
performance analysis.
overview [ experiment-id ]
Write the sample list for the specified experiment,
with data for each sample. experiment-id is the numeric
identifier of the experiment as given by the
experiment_list command. If experiment-id is all or is
omitted, the overviews for all experiments are written.
experiment-id is required on the command line, but not
in a script or in interactive mode.
statistics [ experiment-id ]
Write the execution statistics data for the specified
experiment, aggregating data over the current sample
set. experiment-id is the numeric identifier of the
experiment as given by the experiment_list command. If
experiment-id is omitted, the sum across all experi-
ments, as selected with their samples, is written. If
experiment-id is all, the sum and the statistics for
the selected samples in each experiment are written.
experiment-id is required on the command line, but not
in a script or in interactive mode.
Miscellaneous Commands
mapfile load-object mapfilename
Write the map file for the given load object to map-
filename. If mapfilename is dash (-), write the map
file to stdout. The mapfile produced is ordered by
whatever metric is currently set to sort the function
list.
script script
Process commands from the named script.
help Print help information.
quit Exit interactive mode. If used in a script, no more
commands from that script are processed.
{ Version | version }
Print the current release version of er_print.
# ...
Comment line; used in scripts or a .er.rc file.
Obsolete Commands
address_space
Address space data is no longer supported. An error
message is printed if you use this command.
DEFAULTS
Defaults for many of the reports in er_print and the
displays in the Analyzer can be set in a resource file named
.er.rc. Both er_print and the Performance Analyzer process a
system-wide .er.rc file, then a .er.rc file in the user's
home directory, if present, then a .er.rc file in the
current directory, if present. Directives read from each
file take precedence over directives read previously.
These files can contain scc, dcc, sthresh, dthresh, and name
commands, as described above. They can also contain the
following commands, which cannot be used on the command line
or in scripts:
dmetrics metric_list
Specifies the default order and visibility of metrics.
Multiple dmetrics commands can be given in any er.rc
file, and are concatenated. dmetrics from the various
files are concatenated in the order: current directory,
user's home directory, and system.
The metric_list is described under the metrics command
above with the following additions:
The <visibility> can be "!" which means that no version
of the metric is visible. This allows the user to
specify the order of a metric without making it visible
by default.
Two generic metric names can be specified. "hwc" means
any hardware counter metric, and "any" means any metric
at all.
For all metrics computed from the experiments that have
been loaded, the concatenated list of all dmetrics is
scanned for a match. The first matching entry deter-
mines both the visibility and the ordering of the
metrics in the function list and the callers-callees
list.
dsort metric_list
Specifies the metric to be used by default for sorting
the function list. The first metric in the dsort
specification that matches any metric in the
experiment(s) is used to determine the sort metric,
subject to the following conditions. If the entry in
the dsort metric_list has a <visibility> of "!", the
first metric whose name matches is used, whether it is
visible or not; if any other setting of <visibility> is
used, the first visible metric whose name matches is
used. Like dmetrics, dsort specifications from the
various .er.rc files are concatenated in the order:
current directory, user's home directory, and system.
gdemangle library.so
Set the path to the shared object that supports an API
to demangle C++ function names for other C++ compilers.
The shared object must export the C function,
cplus_demangle(), conforming to the standard GNU
libiberty.so interface. The tools first try to open
the library specified by the gdemangle directive. If
that fails, or no directive is given, they try to open
libiberty.so, assuming that LD_LIBRARY_PATH is set to
find it. If that fails, they try to open
/usr/local/lib/libiberty.so. If that fails, C++ func-
tion names for other C++ compilers are not demangled.
COMPATIBILITY
er_print does not work on experiments recorded with earlier
versions of the tools. If invoked on such experiments, a
warning is printed. Use the version of er_print from the
release with which the experiment was recorded.
SEE ALSO
analyzer(1), collect(1), collector(1), dbx(1),
er_archive(1), er_cp(1), er_export(1), er_mv(1), er_rm(1),
er_src(1), libcollector(3), and the manual
Program Performance Analysis Tools