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 \ will have 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 continuation 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.
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. If the same metric
appears multiple times in the metric_spec, only the
first appearance is processed; subsequent appearances
are ignored.
For example:
metrics i.user:e.%user:i%user
means show inclusive user time, but not percentage, and
exclusive user time and percentage, in that order.
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 experiments loaded can be obtained with
the metric_list command. 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 cmetrics for caller-callees, and
data_metrics for data-derived output to match the
metrics settings. See those commands for further
information.
If a metrics command has an error in it, or there are
no metrics in the specification corresponding to the
current data, ignore the command with a warning, and
keep the previous settings in effect.
sort metric_spec
Sort the function list by the given metric. The
metric_spec is described under metrics; it may 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]
Write the summary 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 directive 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 sort metric (sort). Within
each caller-callee report, the callers and callees are
sorted by the caller-callee sort metrics (csort).
cmetrics metric_spec
Set the caller-callee metrics. The metric_spec is
defined in the metrics section, with the addition of
the <flavor> "a" for attributed.
By default, set the caller-callee metrics to match the
function list metrics whenever they are changed.
Caller-callee attributed metrics are inserted in front
of the corresponding exclusive and inclusive metrics,
with <visibility> corresponding to the logical or of
the <visibility> setting for those two. Static metric
settings are copied to the caller-callee metrics. 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 experiments loaded can be obtained with the
cmetric_list command.
If metric_spec is omitted, print the current caller-
callee metrics setting. If a cmetrics command has an
error in it, ignore it with a warning, and keep the
previous settings in effect.
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 directive is on the command-line, the N is
required; if it would not be needed it is ignored.
csort metric_spec
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 a
static metric. If multiple metrics are specified, sort
by the first visible one that matches.
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.
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]
Write annotated source of the given object file, or of
the object 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, use the Nth possible choice (with the numbering
starting from 1). If an ambiguous name is given
without the numeric specifier N, print a list of
choices instead of the annotated source. Each list item
will contain 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,
report an error; if there is only one possibility,
ignore any such error. 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.
The default source context for any function is defined
as the source file to which the first instruction in
that function is attributed. It is normally the source
file compiled to produce the object module containing
the function. Immediately following the first instruc-
tion, 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 contexts include instructions coming from include
files and instructions from functions inlined into the
named function. If there are any alternate source con-
texts, include a list of extended index lines at the
beginning of the default source context to indicate
where the alternate source contexts are located in the
following form:
<Function: f, instructions from source file src.h>
The function name may also be specified as
function`file`, where file is used to specify an alter-
nate 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 context, metrics will be shown only
for the named function.
If any compiler commentary has been selected, inter-
leave 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 percen-
tage of the maximum for that metric within the file, to
make it easier for the user to find the important
lines. Govern the threshold and the classes of commen-
tary to show using the source-threshold setting,
sthresh, and the preferences setting for source com-
piler commentary, scc.
Search for the file using the path as specified by a
setpath command. If the file is not found, search
under the absolute pathname as recorded in the execut-
able. If the user has moved the sources, or the exper-
iment was recorded in a different file system, the user
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]
Same as source.
disasm { filename | function_name } [N]
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
the user to find the important lines. The threshold is
set using the dthresh command. The classes of commen-
tary 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
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
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 may 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.
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. When the
directive is on the command line, N is required; if it
is not needed it is ignored.
Note: the obsolescent command, data_osingle generates a
warning message but is processed as data_single. It
will be removed in the next release.
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.
Note: the obsolescent command, data_olayout generates a
warning message but is processed as data_layout. It
will be removed in the next release.
data_metrics metric_spec
Set the data-derived metrics. The metric_spec is
defined in the metrics section, except only the <fla-
vor> "d", for data-derived, may be used for dynamic
metrics.
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.
Note: the obsolescent command, data_ometrics generates
a warning message but is processed as data_metrics. It
will be removed in the next release.
data_sort
Set the sort metric for data objects. The prefix "d."
is needed for dynamic metrics, but may be omitted for
static metrics. The data_sort metric must be either a
data-derived metric, or a static metric. If multiple
metrics are specified, sort by the first visible one
that matches.
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] 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. Others can be defined by the user 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
will be as for the Data Space List. The name mobj_type
may 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. Its name 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 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 (").
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_list
Display a two-column list showing the status and names
of available load objects. Show the expand/collapse
status in the first column and the name in the second.
Display a selection status of yes if the load object's
functions are shown in the function list (expanded), or
no 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.
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, its functions are expanded, and all func-
tions that have non-zero metrics are shown in the func-
tion list. If a load object is not selected, its func-
tions are collapsed, and only a single line with
metrics for the entire load object instead of its indi-
vidual functions is shown.
By default, select all load objects.
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.
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 the user's 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 and expert mode are ident-
ical. They show master-thread call stacks and slave-
thread call stacks reconciled, and add special func-
tions, with names of the form <OMP-*> when the OpenMP
runtime is performing certain operations. See the col-
lect(1) man page, or the Performance Analyzer manual
for more information. Machine mode shows machine
callstacks for all threads.
For all other experiments, all three modes show the
same data.
The obsolete javamode command is processed with a warn-
ing in this release, but will become an error in subse-
quent releases.
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 will be prepended to
the header information.
The user is 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
messages 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.
The user is 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.
The user is required to enter exp_id ion the command
line, but not in a script or in interactive mode.
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 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.
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, 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, name, mobj_define 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,
user's 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 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_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, user's home directory, and system.
en_desc {on|off}
Set the mode for reading descendant experiments to on
(enable all descendants) or off (disable all descen-
dants).
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,
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.
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
datamode {on|off}
No longer used. It is ignored with a warning in this
release, and will become an error in subsequent
releases.
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. Order the mapfile produced using the
metric currently set to sort the function list.
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, including THRID, LWPID, CPUID, STACK,
LEAF, VADDR, PADDR, DOBJ, TSTAMP, SAMPLE, EXPID, PID, or the
name of a memory object. Operators include the usual logi-
cal operators and arithmetic (including shift) operators, in
C notation, with C precedence 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, respectively). If-then-else constructs are speci-
fied 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.
COMPATIBILITY
er_print works on experiments recorded with earlier versions
of the tools (Forte Developer 7 or later), but may 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.
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), regex(5), and the Performance
Analyzer manual.