NAME
er_print - print an ASCII report from one or more perfor-
mance 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.
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 input terminal.
-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 input terminal. Input from the input ter-
minal is terminated with the quit command.
Any line that ends in \ has the \ character removed, and the
content of the next line appended before the line is parsed.
There is no limit (other than total memory) to how many con-
tinuation lines you can use. Any arguments that contain
blanks must be surrounded by double quotes ("), whether on
the command line, or read from scripts, or read from a
.er.rc file.
After each command is processed, any error or warning mes-
sages arising from the processing are written. Summary
statistics on the processing can be printed with the
procstats command.
When invoked on more than one experiment or experiment-
group, er_print will come up in comparison mode by default.
See "COMPARISON MODE", below, for more information.
COMMANDS
The commands accepted by the er_print utility 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_spec
Set the function list metrics (the same metrics are
also used for source and disassembly, and for lines and
pcs). metric_spec is a list of metric keywords
separated by colons. For dynamic metrics, that is,
metrics based on measured data, each keyword is of the
form <flavor><visibility><metric-name>. For static
metrics, that is, metrics based on the static proper-
ties of the load objects in the experiments (name,
address, and size), each keyword is of the form
[<visibility>]<metric-name>, with the <visibility> set-
ting being optional.
<flavor> 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 be
shown only as a time or only as a count, "." and "+"
have the same meaning. For hardware counter profiling
experiments, and counters that count 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 static metrics,
"+", ".", and "%" all have the same meaning.
<visibility> can also be specified as a "!", meaning
turn off the metric. It is normally not used, but is
used in the dmetrics command (q.v.), used to set
default metrics to override the built-in visibility
defaults for each type of metric. The same metric can-
not appear multiple times in the metric_spec; if it
does, it is reported as an error. If the metric "name"
is not in the list, it is appended to it. A list of
all the available <metric-name> values for the experi-
ments loaded can be obtained with the metric_list com-
mand. See the collect(1) man page for more information
on metrics.
By default, use the metric setting based on the
dmetrics command, processed from .er.rc files, as
described under default-setting commands, below. If a
metrics command explicitly sets metric_spec to default,
restore the default settings appropriate to the data
recorded. When metrics are reset, the default sort
metric is set in the new list. If metric_spec is omit-
ted, print the current metrics setting.
In addition to setting the metrics for the function
list, etc., set the metrics for caller-callees, for
data-derived output, and for index-objects to match the
metrics settings.
If a metrics command has an error in it, or no metrics
in the specification correspond to the current data,
ignore the command with a warning, and keep the previ-
ous settings in effect.
sort metric_spec
Sort the function list by the given metric. The
metric_spec is described under metrics; it can be pre-
ceeded by a "-" sign, specifying reverse sort. 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
more than one metric is named in the metric_spec, use
the first one that is visible. If none of the metrics
named are visible, ignore the command.
By default, use the metric sort setting based on the
dsort command, processed from .er.rc files, as
described under default-setting commands, below. If a
sort command explicitly sets metric_spec to default,
use the default settings.
If metric_spec is omitted, print the current sort
metric.
fsummary
Write the summary panel for each function in the func-
tion list, in the order specified by the current sort
metric. Include any load objects in the function list
whose functions are hidden with the object_select com-
mand.
fsingle function_name [N | ADDR]
Write the summary panel for the named function. The
optional parameter is needed for those cases where the
function name is ambiguous; see under the "source" com-
mand for more information.
Commands Controlling the Callers-Callees List
callers-callees
Write the callers-callees panel for each function,
based on the last metrics specification, in the order
specified by the function sort metric (sort).
cmetrics metric_spec
Obsolete, and no longer supported.
The caller-callee metrics are set to match the function
list metrics.
If metric_spec is omitted, print the current caller-
callee metrics setting.
csort metric_spec
Obsolete, and no longer supported.
Whenever metrics are set, either explicitly or by
default, set the caller-callee sort metric based on the
function metrics: if sorting is by a dynamic metric,
either inclusive or exclusive, sort by the correspond-
ing attributed metric; if sorting is by a static
metric, sort by it.
If metric-spec is omitted, print the current callers-
callees sort metric.
csingle function_name [N | ADDR]
Write the callers-callees panel for the named function.
The optional parameter is needed for those cases where
the function name is ambiguous; see under the "source"
command for more information.
The caller-callee panel can also be generated for a
callstack fragment. The initial frame in the fragment
is set by the csingl command. Additional frames may be
added by the cprepend or cappend commands; frames may
be removed by the crmfirst and crmlast commands. After
each frame is added or removed from the callstack frag-
ment, the panel showing all callers into the current
fragment, and all callees from that fragment is
printed.
cprepend function_name [N | ADDR]
Prepend the named function to the current callstack
fragment. The optional parameter is needed where the
function name is ambiguous; see under the "source" com-
mand for more information.
cappend function_name [N | ADDR]
Append the named function to the current callstack
fragment. The optional parameter is needed where the
function name is ambiguous; see under the "source" com-
mand for more information.
crmfirst
Remove the top frame from the callstack segment.
crmlast
Remove the bottom frame from the callstack segment.
Command Controlling the Calltree List
calltree
Write the dynamic callgraph from the experiment, show-
ing the hierarchical metrics at each level.
Commands Controlling Leak and Allocation Lists
leaks
Write the list of leaks, sorted by size, along with the
call stack for each. Aggregate the entries in the leak
list by common call stack.
allocs
Write the list of allocations, sorted by size, along
with the call stack for each. Aggregate the entries in
the allocations list by common call stack.
Commands Controlling Source and Disassembly Listings
pcs Write a list of program counters (PCs) and their
metrics, ordered by the current sort metric. Include
lines in the list that show aggregated metrics for each
load object whose functions are hidden with the
object_select command.
psummary
Write the summary metrics panel for each PC in the PC
list, in the order specified by the current sort
metric.
lines
Write a list of source lines and their metrics, ordered
by the current sort metric. Include lines in the list
that show aggregated metrics for each function that
does not have line-number information, or whose source
file is unknown. Also include lines that show aggre-
gated metrics for each load object whose functions are
hidden with the object_select command.
lsummary
Write the summary metrics panel for each line in the
lines list, in the order specified by the current sort
metric.
source { filename | function_name } [N | ADDR]
Write annotated source of the given object file, or of
the object file containing the given function. If the
name of the function is a that of a C++ function or a
Java method, the demangled name, in either short or
long form, or the mangled name can be used. If the
demangled name contains spaces, it must be surrounded
by double quotes. The optional parameter, N or ADDR,
is needed for those cases where the file name or func-
tion name is ambiguous. If the N form is used, pick
the Nth possible choice (with the numbering starting
from 1). If there is more than one possibility, and
the N supplied is not within the possible range, report
an error; if there is only one possibility, ignore any
such error.
If the ADDR form is used, it is written as @segment-
number:address. The segment-number:address values should be
specified exactly as they appear as the address metric for
the function.
If an ambiguous name is given without the specifier, print a
list of choices 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.
The default source context for any function is defined as
the source file to which the first instruction in that func-
tion is attributed. It is normally the source file compiled
to produce the object module containing the function.
Immediately following the first instruction, add an index
line for the function. Display index lines as text within
angle brackets in the form shown below:
<Function: f_name>
Alternate source contexts consist of other files that have
instructions in the function attributed to them. Such con-
texts include instructions coming from include files and
instructions from functions inlined into the named function.
If there are any alternate source contexts, include a list
of extended index lines at the beginning of the default
source context to indicate where the alternate source con-
texts are located in the following form:
<Function: f, instructions from source file src.h>
The function name can also be specified as function`file`,
where file is used to specify an alternate source context
for the function.
Note: If the -source argument is used when invoking er_print
on the command line, the backslash escape character must
prepend the file quotes. In other words, the function name
is written as function\`file\`. The backslash is not
required, and should not be used, when er_print is in
interactive mode.
Normally, when the default source context is used, metrics
are shown for all functions from the source file. If the
source file is explicitly used as an alternate source con-
text, metrics are shown only for the named function.
If any compiler commentary has been selected, interleave the
commentary with the source lines in the source listing.
Prepend the string "##" to lines with metrics that are equal
to or exceed a threshold percentage of the maximum for that
metric within the file, to make it easier for you to find
the important lines. Govern the threshold and the classes
of commentary to show using the source-threshold setting,
sthresh, and the preferences setting for source compiler
commentary, scc.
Search for the file using the path as specified by a setpath
command. If the file is not found, search under the abso-
lute pathname as recorded in the executable. If you have
moved the sources, or the experiment was recorded in a dif-
ferent file system, you put a symbolic link from the current
directory to the real source location in order to see the
annotated source, or copy the source code and load objects
into the experiment.
src { filename | function_name } [N | ADDR]
Same as source.
disasm { filename | function_name } [N | ADDR]
Write annotated disassembly of the given object file,
or of the object file containing the given function.
Ambiguities are resolved in the same way as for the
source command.
Prepend the line with "##" if the metric value on a
line equals or exceeds a threshold percentage of the
maximum value of that metric. This makes it easier for
you to find the important lines. The threshold is set
using the dthresh command. The classes of commentary
shown are set by the dcc command.
Search for the source file corresponding to the speci-
fied disassembly as described for the source command,
and interleave the the disassembly with the source and
index lines. If the function includes code from an
alternate source context, insert an index line refer-
ring to the alternate context, followed by the raw
disassembly without compiler commentary. If the source
file cannot be found, show the disassembly without the
source and without the compiler commentary.
scc com_spec
Specify which classes of compiler commentary are shown
with annotated source. com_spec 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
co[degen] - show code generator messages
cf - show compile flags at the bottom of the
source
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
Flag a line 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, use the default setting:
scc all
If com_spec is not specified, turn off compiler commen-
tary. The scc command is normally used only in a
.er.rc file.
sthresh value
Set the threshold for flagging important lines in the
source. Flag a line as important if it has a metric
value that is greater than value percent of the largest
value of that metric on any line in the file. The
default value of value is 75.
dcc com_spec
Specify which classes of compiler commentary are shown
with annotated disassembly. The com_spec specification
for this command can include any of the scc classes and
the following additional specifications:
h[ex] - show the hexadecimal representation of
each instruction
noh[ex] - do not show the hexadecimal representa-
tion of each instruction
s[rc] - interleave source in disassembly (default)
as[rc] - interleave annotated source, with
source-line metrics, in disassembly
nos[rc] - do not interleave source in disassembly
If no dcc command is given, use the default setting:
dcc all:src
This command is normally used only in a .er.rc file.
cc com_spec
Specify compiler-commentary for both source and
disassembly
dthresh value
Set the threshold for flagging important lines in the
disassembly. Flag a line as important if it has a
metric value which is greater than value percent of the
largest value of that metric on any line in the file.
The default value of value is 75.
setpath path_list
Set the path used to find source, object, etc. files.
path_list is a colon-separated list of directories. If
any directory has a colon character in it, it should be
escaped with a backslash. The special directory name,
$expts, refers to the set of current experiments, in
the order in which they were loaded; it can be abbrevi-
ated with a single $ character.
The default setting is: "$expts:.". Use the compiled-
in full pathname if a file cannot be found by searching
the current path.
setpath with no argument means print the current path.
addpath path_list
Append path_list to the current setpath settings.
pathmap old_prefix new_prefix
If a file can not be found useing the path_list as set
by addpath or setpath, one or more path remappings can
be supplied. Any pathname for a source file, object
file, or shared object that begins with the old_prefix
has that prefix replaced by the new_prefix, and the
resulting path used to find the file. Multiple pathmap
commands can be supplied, and they are each tried until
the file is found.
Commands Controlling the Data Space List
Data Space commands are applicable only to hardware counter
experiments where aggressive backtracking was specified, and
for objects in files that were compiled with -xhwcprof.
(Available on SPARC[R] platforms for C or C++ only.) See
the compiler manual for further information.
data_objects
Write the list of data objects with their metrics.
data_single
name [N]
Write the summary metrics panel for the named data
object. The optional parameter N is needed for those
cases where the object name is ambiguous.
data_layout
Write the annotated data object layouts for all program
data objects with data-derived metric data, sorted by
the current data sort metric values for the structures
as a whole. Show each aggregate data object with the
total metrics attributed to it, followed by all of its
elements in offset order, each with their own metrics
and an indicator of its size and location relative to
32-byte blocks.
data_metrics metric_spec
Obsolete, and no longer supported.
By default, set the data-derived metrics to match the
function list metrics whenever they are changed. Set
the data-derived metrics corresponding to any visible
exclusive or inclusive metric that has a data-derived
flavor, with <visibility> corresponding to the logical
or of the <visibility> setting for those two. Copy
static metric settings to the data-derived metrics. If
the metric "name" is not in the list, it is appended to
it.
If metric_spec is omitted, print the current data-
derived metrics setting. A list of all the available
<metric-name> values for the experiments loaded can be
obtained with the data_metric_list command.
If the metric_spec has any errors, it is ignored, and
the data-derived metrics are left unchanged.
data_sort
Obsolete, and no longer supported.
Whenever metrics are set, either explicitly or by
default, set the data-derived sort metric based on the
function metrics: if sorting is by a dynamic metric,
either inclusive or exclusive, which has a correspond-
ing data-derived flavor, sort by the corresponding
data-derived metric; if sorting is is by an inclusive
or exclusive metric that does not have a data-derived
flavor, sort by the first visible data-derived metric;
if sorting is by a static metric, sort by it.
Commands Controlling the Memory Object Lists
Memory Object commands are applicable only to hardware
counter experiments where aggressive backtracking was speci-
fied, and for objects in files that were compiled with
-xhwcprof. (Available on SPARC[R]-based platforms for C or
C++ only.) See the compiler manual for further information.
Memory Objects are components in the memory subsystem, such
as cache-lines, pages, memory-banks, etc. The object is
determined from an index computed from the virtual and/or
physical address as recorded. Memory objects are predefined
for virtual and physical pages, for sizes of 8KB, 64KB,
512KB, and 4 MB. You can define others with the mobj_define
command.
The following commands control the Memory Object Lists.
memobj mobj_type
Write the list of the memory objects of the given type
with the current metrics. Metrics used and sorting are
the same as for the Data Space List. The name
mobj_type can also be used directly as the command.
mobj_list
Write the list of known types of memory objects, as
used for mobj_type in the memobj command.
mobj_define mobj_type index_exp
Define a new type of memory objects with a mapping of
VA/PA to the object given by the index_exp. The syntax
of the expression is described under "EXPRESSION GRAM-
MAR", below. The mobj_type must not already be
defined, and it cannot match any existing command, or
any Index Object type (see below). Its name is case-
insensitive, and must be entirely composed of
alphanumeric characters or the '_' character, and begin
with an alphabetic character. The index_exp must be
syntactically correct. If not, an error is returned and
the definition is ignored. If the index_exp contains
any blanks, it must be surrounded by double quote (").
The <Unknown> memory object has index -1, and the
expression used to define a new memory object should
support recognizing <Unknown>. For example, for
VADDR-based objects, the expression should be of the
form:
VADDR>255?<expression>:-1
and for PADDR-based objects, the expression should be
of the form:
PADDR>0?<expression>:-1
Commands Controlling the Index Object Lists
Index Object commands are applicable to all experiments. An
Index Object is a class of objects that can be indexed by a
formula that is computed from the header of a packet. Index
objects are predefined for Threads, CPUs, Samples, and
Seconds. You can be define others with the indxobj_define
command.
The following commands control the Index Object Lists.
indxobj indxobj_type
Write the list of the index objects of the given type
with the current index object metrics. Metrics used
and sorting are the same as for the Function List, but
containing Exlusive metrics only. The name
indxobj_type can also be used directly as the command.
indxobj_list
Write the list of known types of index objects, as used
for indxobj_type in the indxobj command.
indxobj_define indxobj_type index_exp
Define a new type of index objects with a mapping of
packets to the object given by the index_exp. The syn-
tax of the expression is described under "EXPRESSION
GRAMMAR", below. The indxobj_type must not already be
defined, and it cannot match any existing command, or
any Memory Object type (see above). Its name is case-
insensitive, and must be entirely composed of
alphanumeric characters or the '_' character, and begin
with an alphabetic character. The index_exp must be
syntactically correct. If not, an error is returned and
the definition is ignored. If the index_exp contains
any blanks, it must be surrounded by double quote (").
indxobj_metrics metric_spec
Obsolete, and no longer supported.
By default, set the index-object metrics to match the
function list metrics whenever they are changed. Set
the exclusive index-object metrics corresponding to any
visible exclusive or inclusive metric, with <visibil-
ity> corresponding to the logical or of the <visibil-
ity> setting for those two. Copy static metric set-
tings to the index-object metrics. If the metric
"name" is not in the list, it is appended to it.
If metric_spec is omitted, print the current index-
object metrics setting. A list of all the available
<metric-name> values for the experiments loaded can be
obtained with the indx_metric_list command.
If the metric_spec has any errors, it is ignored, and
the index-object metrics are left unchanged.
indxobj_sort
Obsolete, and no longer supported. Whenever metrics
are set, either explicitly or by default, set the
index-object sort metric based on the function metrics:
if sorting is by a dynamic metric, either inclusive or
exclusive, sort by the corresponding exclusive metric;
if sorting is by a static metric, sort by it.
Commands for the OpenMP Index Objects
OMP_preg
Print a list of the OpenMP Parallel Regions executed in
the experiment, with their metrics. This command is
available only for experiments with OpenMP 3.0 Perfor-
mance data.
OMP_task
Print a list of the OpenMP Tasks executed in the exper-
iment, with their metrics. This command is available
only for experiments with OpenMP 3.0 Performance data.
Commands Controlling the Thread Analyzer Reports
races
Write the report on any detected groups of data-races
in the experiment. Data-race reports are available
only from experiments with data-race-detection data.
rdetail [ race_id ]
Write detailed information on the specified data-race.
If race_id is given as all, write the detailed informa-
tion for all data-races. Data-race reports are avail-
able only from experiments with data-race-detection
data.
rsummary [ race_id ]
Same as rdetail.
deadlocks
Write the report on any detected deadlocks in the
experiment. Deadlock reports are available only from
experiments with deadlock-detection data.
ddetail [ deadlock_id ]
Write detailed information on the specified deadlocks.
If deadlock_id is given as all, write the detailed
information for all data-races. Deadlock reports are
available only from experiments with deadlock-detection
data.
dsummary [ deadlock_id ]
Same as ddetail.
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 LWPs, and a PID, which
can be used for advanced filtering.
sample_list
Display the list of samples processed during the
experiment(s).
lwp_list
Display the list of LWPs processed during the
experiment(s).
thread_list
Display the list of threads processed during the
experiment(s).
cpu_list
Display the list of CPUs used during the experiment(s).
Commands Controlling Filtering of Experiment Data
There are two ways to specify filtering of experiment data,
either by specifying a filter expression, which is evaluated
for each data record to determine whether or not the record
should be included, or with the older commands to select
experiments, samples, threads, CPUs, and LWPs for filtering.
The filtering by expression is controlled by the following
command.
filters filter_exp
filter_exp is an expression which evaluates as true for
any data record that should be included, and false for
records that should not be included.
The grammar of the expression in the filters command is
described under "EXPRESSION GRAMMAR", below. If the expres-
sion contains any blanks, it must be surrounded by double
quotes (").
describe
Print the list of tokens that can be used to build a
filter expression.
The following old-style commands select the experiments,
samples, threads, CPUs, and LWPs for which data is displayed
for filtering.
sample_select sample_spec
sample_spec is a sample list, as described below.
lwp_select lwp_spec
lwp_spec is a LWP list, as described below.
thread_select thread_spec
thread_spec is a thread list, as described below.
cpu_select cpu_spec
cpu_spec is a CPU 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.
Apply the experiment selection from any of the select com-
mands to all four select targets -- threads, LWPs, CPUs and
samples. Retain each experiment in the experiment list, if a
selection of threads, LWPs, CPUs or samples exists; if no
experiment is specified by the user, select all experiments.
Turn off selections for experiments not in the experiment
list.
Some examples:
thread_select 1
Select 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
Select all threads from experiments 1 and 2, as listed
by exp_list.
thread_select 1:1+2:2
Select thread 1 from experiment 1 and thread 2 from
experiment 2.
Commands Controlling Load Object Function Expand/Collapse
object_show object1,object2,...
Set all named load objects to show all their functions.
The names of the objects can be either full pathnames
or the basename. If the name contains a comma charac-
ter, the name must be surrounded by double quotes. If
the string all is used to name the load object, func-
tions are shown for all load objects
object_hide object1,object2,...
Set all named load objects to hide all their functions.
The names of the objects can be either full pathnames
or the basename. If the name contains a comma charac-
ter, the name must be surrounded by double quotes. If
the string all is used to name the load object, func-
tions are shown for all load objects
object_api object1,object2,...
Set all named load objects to show all only the func-
tions representing entry points into the library. 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 the
string all is used to name the load object, only the
entry-point functions are shown for all load objects
objects_default
Set all load objects according to the initial defaults
from .er.rc file processing.
object_list
Display a two-column list showing the status and names
of all load objects. Show the show/hide/api status in
the first column and the name in the second. Display a
status of show if the load object's functions are shown
in the function list (expanded), or API-only if only
the functions representing entry points into the load
object are shown, or hide if its functions are not
shown in the function list (collapsed). All functions
for a collapsed load-object map to a single entry in
the function list representing the entire load object,
or API-only if only those functions representing the
entry point into the load object are shown.
The object_show, object_hide, or object_api commands
are processed in the order encountered, and any subse-
quent command will override any previous commands for
that load object (or all load objects).
object_select object1,object2,...
Set the list of active load objects. Functions from
all named load objects are shown; functions from all
others are hidden. 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 functions from a load object are shown, all func-
tions that have non-zero metrics are shown in the func-
tion list. If a functions from a load object are hid-
den, its functions are collapsed, and only a single
line with metrics for the entire load object instead of
its individual functions is shown.
By default, show functions from all load objects,
except the <Unknown> object..
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. Display the list in the same
way as the metric_list output, but include attributed
metrics additionally.
data_metric_list
Display the currently selected data-derived metrics and
a list of metrics and keyword names for all data-
derived reports. Display the list in the same way as
the metric_list output, but include only those metrics
that have a data-derived flavor, and static metrics.
indx_metric_list
Display the currently selected index object metrics and
a list of metrics and keyword names for all index
object reports. Display the list in the same way as
the metric_list output, but include only those metrics
that have a exclusive flavor, and static metrics.
Commands Controlling the Output
outfile filename
Close any open output file and open filename for subse-
quent output. When opening filename, clear any pre-
existing content. If filename is a minus sign (-),
write output to stdout.
If filename is a pair of minus signs (--), write output
to stderr.
appendfile filename
Close any open output file and open filename, preserv-
ing any pre-existing content, so that subsequent output
is appended to the end of the file. If filename does
not exist, the functionality of appendfile is the same
as for outfile.
limit n
Limit any output to the first n entries of the report,
where n is an unsigned integer.
name { long | short | mangled } [:{soname | nosoname }]
Use long or short form of C++ function names. If
soname is specified, append the shared-object name to
the function name.
viewmode { user | expert | machine }
Set the viewing mode to user, expert or machine.
For Java experiments, user mode shows Java call stacks
for Java threads, and does not show housekeeping
threads. The function list includes a function <JVM-
System>, representing aggregated time from non-Java
threads. When the JVM software does not report a Java
call stack, time is reported against the function
<no Java callstack recorded>. Expert mode shows Java
call stack for Java threads when your Java code is
being executed, and a machine call stack when JVM code
is being executed or when the JVM software does not
report a Java call stack. It shows machine call stacks
for non-user-Java (housekeeping) threads. Machine mode
shows machine call stacks for all threads.
For OpenMP experiments, user mode shows reconstructed
call stacks similar to those obtained when the program
is complied without OpenMP. Expert mode exposes com-
piler generated functions representing parallelized
loops, tasks, etc., which are aggregated with user
functions in user mode. In both modes, special func-
tions, with names of the form <OMP-*>, are shown when
the OpenMP runtime is performing certain operations
For all other experiments, all three modes show the
same data.
compare [on||off]
Set comparison mode off (compare off, the default), or
on compare 0, when multiple experiments are read, the
data is aggregated. If comparison is enabled, and mul-
tiple experiments are loaded, separate columns of
metrics will be shown for the data from each experiment
Commands That Print Other Information
header [ exp_id ]
Write descriptive information about the specified
experiment. exp_id is the numeric identifier of the
experiment as given by the experiment_list command. If
exp_id is all or is omitted, write the headers of all
experiments. Following each header, print any errors
or warnings. Separate headers for each experiment by a
line of dashes.
If the experiment directory contains a file named
notes, the contents of that file are prepended to the
header information.
You are required to enter exp_id 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 [ exp_id ]
Write the sample list for the specified experiment,
with data for each sample. exp_id is the numeric iden-
tifier of the experiment as given by the
experiment_list command. If exp_id is all or is omit-
ted, write overviews for all experiments.
You are required to enter exp_id on the command line,
but not in a script or in interactive mode.
statistics [ exp_id ]
Write the execution statistics data for the specified
experiment, aggregating data over the current sample
set. exp_id is the numeric identifier of the experiment
as given by the experiment_list command. If exp_id is
omitted, write the sum across all experiments, as
selected by their samples. If exp_id is all, write the
sum and the statistics for the selected samples in each
experiment.
You are required to enter exp_id on the command line,
but not in a script or in interactive mode.
ifreq
Write the instruction-execution summary. Instruction
frequency reports are available only from experiments
with count data. (Available for SPARC systems only.)
Default-setting Commands
Defaults for many of the reports in the er_print utility and
the er_src utility, as well as the displays in the Analyzer,
can be set in a resource file named .er.rc. Both the
er_print utility and the Performance Analyzer process a
system-wide .er.rc file, then a .er.rc file in your 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.
Note: Since the defaults for the Analyzer, the er_print
utility, and the er_src utility are all set by a com-
mon .er.rc file, the output of the er_print utility
is affected by saving changes in the Analyzer's Set
Data Preferences dialog box, or by using any editor
to change a .er.rc file.
The Analyzer puts a message into its Errors/Warning Logs
areas naming the user .er.rc files it processed. The
er_print utility and the er_src utility print a message to
stderr naming those files.
These files can contain scc, sthresh, dcc, dthresh, setpath,
addpath, pathmap, name, mobj_define, object_show,
object_hide, object_api, compare, and viewmode commands, as
described above. They can also contain the following com-
mands, which cannot be used on the command line or in
scripts:
dmetrics metric_spec
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,
your home directory, and system.
The metric_spec 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 you 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_spec
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_spec 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, your home directory, and system.
en_desc option
Set the mode for reading descendant experiments
according to option The allowed values of option are:
Value Meaning
on Show all experiments on descendant processes
(the default)
off Do not show any experiments on descendant
processes
=<regex> Show those experiments on descendant
processes whose lineage or executable name
match the regular expression.
If any experiments that are loaded have descendants
that are not loaded as a result of the en_desc setting,
a message is printed from er_print and a popup is
posted from the Performance Analyzer.
Default-setting Commands that only Affect the Performance
Analyzer
tabs tab_spec
Set the default set of tabs to be visible in the
Analyzer. The tabs are named by the er_print command
that generates the corresponding reports; in addition,
mpi_timeline specifies the MPI Timeline tab, mpi_chart
specifies the MPI Chart tab, timeline specifies the
Timeline tab, and headers specifies the Experiments
tab. Only those tabs that are supported by the data in
the loaded experiments are shown.
rtabs tab_spec
Set the default set of tabs to be visible in the
Analyzer, when invoked with the tha command (as opposed
to being invoked as analyzer).
tlmode tl_mode
Set the display mode options for the Timeline tab.
tl_mode is a colon-separated list of options, which are
described in the following table.
Value Meaning
lw[p] Display events for LWPs
t[hread] Display events for threads
c[pu] Display events for CPUs
r[oot] Align call stack at the root
le[af] Align call stack at the leaf
d[epth]=nn
Set the maximum depth of the call stack that
can be displayed
lwp, thread, and cpu are mutually exclusive, as are
root and leaf. If more than one mutually exclusive
option is specified, only the last one is used.
tldata tl_data
Select the default data types shown in the Timeline.
tl_data is a colon-separated list of types, which are
listed in the following table.
Value Meaning
sa[mple] Display sample data
c[lock] Display clock profiling data
hw[c] Display hardware counter profiling data
sy[nctrace]
Display thread synchronization tracing data
mp[itrace]
Display MPI tracing data
he[aptrace]
Display heap tracing data
Miscellaneous Commands
mapfile load-object mapfilename
Obsolete, and no longer supported.
procstats
Print the accumulated statistics from processing data.
script script
Process commands from the named script.
version
Print the current release version of er_print.
quit Exit interactive mode. If used in a script, no more
commands from that script are processed.
help Print help information.
# ...
Comment line; used in scripts or a .er.rc file.
EXPRESSION GRAMMAR
A common grammar is used for an expression defining a
filter, and an expression used to compute a memory object
index.
The grammar specifies an expression as a combination of
operators and operands. For filters, if the expression
evaluates to true, the packet is included; if the expression
evaluates to false, the packet is excluded. For memory
objects, the expression is evaluated to an index that
defines the particular memory object referenced in the
packet.
Operands in an expression are either constants, or fields
within a data record, as listed with the describe command.
The operands include THRID, LWPID, CPUID, STACK, LEAF,
VIRTPC, PHYSPC, VADDR, PADDR, DOBJ, TSTAMP, SAMPLE, EXPID,
PID, or the name of a memory object. Operand names are
case-insensitive.
VIRTPC, PHYSPC, VADDR, and PADDR are non-zero only when "+"
is specified for Hardware-counter- or clock-profiling.
Furthermore, VADDR is less than 256 when the real virtual
address could not be determined. PADDR is zero if VADDR
could not be determined, or if the virtual address could not
be mapped to a physical address. Likewise, VIRTPC is zero
if backtracking failed, or was not requested, and PHYSPC is
zero if either VIRTPC is zero, or the VIRTPC could not be
mapped to a physical address.
Operators include the usual logical operators and arithmetic
(including shift) operators, in C notation, with C pre-
cedence rules, and an operator for determining whether an
element is in a set (IN) or whether any or all of a set of
elements is contained in a set (SOME IN or IN, respec-
tively). If-then-else constructs are specified as in C,
with the ? and : operators. Parentheses should be used to
ensure proper parsing of all expressions. On the er_print
command-line, the expression cannot be split across lines.
In scripts, or on the command-line, the expression must be
inside double quotes if it contains any blanks.
Filter expressions evaluate to a boolean, true if the packet
should be included, and false if it should not be included.
Thread, TWP, CPU, experiment-id, process pid, and sample
filtering are based on a relational expression between the
appropriate keyword and an integer, or using the IN operator
and a comma-separated list of integers.
Time-filtering is used by specifying one or more relational
expressions between TSTAMP and a time, given in integer
nanoseconds from the start of the experiment whose packets
are being processed. Times for samples can be obtained from
the overview command; Times in the overview command are
given in seconds, and must be converted to nanoseconds for
time-filtering. Times can also be obtained from the
Analyzer's Timeline display.
Function filtering can be based either on the leaf function,
or on any function in the stack. Filtering by leaf function
is specified by a relational expression between the LEAF
keyword and an integer function id, or using the IN operator
and the construct FNAME("<regex>"), where <regex> is a regu-
lar expression, as specified on the regex(5) man page. The
entire name of the function, as given by the current setting
of name, must match.
Filtering based on any function in the call stack is speci-
fied by determining if any function in the construct
FNAME("<regex>") is in the array of functions represented by
the keyword STACK:
(FNAME("myfunc") SOME IN STACK)
Data object filtering is analogous to stack function filter-
ing, using the DOBJ keyword and the construct
DNAME("<regex>") enclosed in parentheses.
Memory object filtering is specified by using the name of
the memory object, as shown in the mobj_list command, and
the integer index of the object, or the indices of a set of
objects. (The <Unknown> memory object has index -1.)
Data object filtering and memory object filtering are mean-
ingful only for hardware counter packets with dataspace
data; all other packets are excluded under such filtering.
Direct filtering of virtual addresses or physical addresses
is specified by a relational expression between VADDR or
PADDR, and the address.
Memory object definitions (the mobj_define command) use an
expression that evaluates to an integer index, using either
the VADDR keyword or PADDR keyword. They are applicable
only to hardware counter packets for memory counters and
dataspace data. The expression should return an integer, or
-1 for the <Unknown> memory object.
COMPARISON MODE
When er_print is invoked on more than one experiment or
experiment group, it will aggregate the data. If the com-
pare command is used to enable comparison, the function list
will show separate columns of metrics for each experiment or
group, so that the data may be compared. The current
implementation is a prototype, and the functionality is
expected to change for the next release.
COMPATIBILITY
er_print works on experiments recorded with earlier versions
of the tools (Forte Developer 7 software or later), but
might not work on experiments recorded with future versions.
If invoked on such experiments, a warning is printed. Use
the version of er_print from the release with which the
experiment was recorded. A warning is also posted when
reading any experiment recorded with versions prior to Sun
Studio 12 software, saying that the experiments will not be
readable with future releases.
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), tha(1), regex(5), and the Per-
formance Analyzer manual.