Analyzing Program Performance with Sun WorkShop |
er_print
ReferenceThis chapter explains how to use the
er_print
utility. It covers the following topics:
er_print
is a Sun WorkShop utility that prints out an ASCII version of the various displays supported by the Analyzer. The information is written to standard output unless you redirect it to a file or printer. You must giveer_print
the name of one or more experiment-record files generated by the Sampling Collector as arguments. Provided the Collector has stored the data in the experiment-record file, you can display metrics of performance for functions, callers and callees, source code and disassembly listings; sampling information; address-space data; and execution statistics.
- For a description of the data collected by the Sampling Collector, see Chapter 3.
- For instructions on how to use the Analyzer to display information in a graphical format, see Chapter 4.
er_print
is available with the Sun WorkShop compilers for C, C++, Fortran 77, and Fortran 95, and with the Assembler.
er_print
SyntaxThe command-line syntax for
er_print
is:
er_print [-script script | -command | -] exper_1 exper_2...exper_nOptions
er_print
accepts the following options:
-
Read er_print
commands entered at the terminal.-script
scriptRead commands from the file script, which contains a list of er_print
commands (see "er_print Commands" ), one per line. If the-script
option is not present,er_print
reads commands from the terminal or from the command line.-
commandProcess the given command.
Multiple options can appear on the
er_print
command line. They are processed in the order they appear. You can mix scripts, "-
" arguments, and explicit commands in any order. If you do not supply any command or script arguments,er_print
acts as if you had given a "-
" argument: It goes into interactive mode to read commands entered from the keyboard.
er_print
CommandsThe commands accepted by
er_print
are listed in the following sections. You can abbreviate any command with a shorter string as long as the command is unambiguous.Function List Commands
The following commands control the display of function information.
- Write the function list with the currently selected metrics.
- Default is exclusive and inclusive user CPU time, in both seconds and percentage of total program metric. You can change the current metrics displayed with the
metrics
command.
- Write a summary metrics panel for each function in the function list.
- For a description of the summary metrics for a function, see Viewing Summary Metrics for a Function or Load Object.
- Specify a new current selection of function-list metrics.
- metric_spec is a list of metric keywords, separated by colons. For example:
%metrics i.user:i%user:e.user:e%user
- This command instructs
er_print
to display:
- inclusive user CPU time in seconds
- inclusive user CPU time percentage
- exclusive user CPU time in seconds
- exclusive user CPU time percentage
- When the
metrics
command has finished executing, it prints a message showing the new current metric selection. For example:
current: e.user:e%user:i.user:i%user:names- To see a listing of the currently selected metrics, use the
functions
command.
Note For a list of all availableer_print
metric keywords, see TABLE 5-1. To generate a listing of the keywords available for your experiment, use themetric_list
orcmetric_list
command.
- Write the load-object list with the currently selected metrics.
- Default is exclusive and inclusive user CPU time, in seconds and percentage of total program metric. You can change the current metrics displayed with the
metrics
command.
- Write a summary metrics panel for each load object in the load-object list.
- For a description of the summary metrics for a load object, see Viewing Summary Metrics for a Function or Load Object.
Callers-Callees List Commands
The following commands control the display of caller and callee information.
- Print the callers-callees panel for each of the functions, in the order in which they are sorted. The selected (middle) function is marked with an asterisk. For example:
Excl. User Incl. User Attr. User NameCPU sec. CPU sec. CPU sec.0. 0.010 0.010 _doprnt0. 0. 0. _xflsbuf0. 0.010 0. *_realbufend0. 0.620 0. _rw_rdlock0. 0.010 0.010 rw_unlock- In this example,
_realbufend
is the selected function; it is called by_doprnt
and_xflsbuf
, and it calls_rw_rdlock
andrw_unlock
.
- Specify a new current selection of caller-callee metrics.
- metric_spec is a list of metric keywords, separated by colons. For example:
%cmetrics i.user:i%user:a.user:a%user
- This command instructs
er_print
to display:
- Inclusive user CPU time in seconds
- Inclusive user CPU time percentage
- Attributed user CPU time in seconds
- Attributed user CPU time percentage
- To see a listing of the currently selected metrics, use the
callers-callees
command.
Note For a list of all availableer_print
metric keywords, see TABLE 5-1. To generate a listing of the keywords available for your experiment, use themetric_list
orcmetric_list
command.
Source and Disassembly Listing Commands
The following commands control the display of annotated source and disassembly code.
disasm {
file|
function} [
N]
- Write out annotated disassembly code for either the specified file, or the file containing the specified function. The file in either case must be in a directory in your path.
- You use the optional parameter N (an integer equal to 1 or greater) only in those cases where the file or function name is ambiguous; in this case, the Nth possible choice is used. If you give an ambiguous name without the numeric specifier,
er_print
prints a list of possible object-file names; if the name you gave was a function, the name of the function is appended to the object-file name, and the number that represents the value of N for that object file is also printed.
source | src {
file|
function} [
N]
- Write out annotated source code for either the specified file or the file containing the specified function. The file in either case must be in a directory in your path.
- You use the optional parameter N (an integer equal to 1 or greater) only in those cases where the file or function name is ambiguous; in this case, the Nth possible choice is used. If you give an ambiguous name without the numeric specifier,
er_print
prints a list of possible object-file names; if the name you gave was a function, the name of the function is appended to the object-file name, and the number that represents the value of N for that object file is also printed.Selectivity Commands: Samples, Threads, LWPs, and Load Objects
The following commands control selection of samples, threads, and LWPs for display.
- Select the load objects about which you want to display information. object_spec is a list of load objects, separated by commas but no spaces. If an object name itself contains a comma, you must surround the comma with double quotation marks.
- The names of the objects should be either full pathnames, or the basename.
- For example:
Metric Commands
The following commands list available metric specification keywords.
- Display a list of metric keywords that you can use in other commands (for example,
metrics
andsort
) to reference various types of metrics in the function list.- A keyword, except for the
size
,address
, andname
keywords, consists of the lettere
(exclusive),i
(inclusive), ora
(attributed); a period (.
), which indicates an absolute value, or a percent sign (%
), which indicates percentage of total program metric; and a character string describing the metric.- Attributed metrics can be specified for display only with the
cmetrics
command, not themetrics
command, and displayed only with thecallers-callees
command, not thefunctions
command.TABLE 5-1 lists the available
er_print
metric keywords.
- Display a list of metric keywords that you can use in other commands (for example,
cmetrics
andcsort
) to reference various types of metrics in the callers-callees list.- A keyword, except for the
size
,address
, andname
keywords, consists of the lettere
(exclusive),i
(inclusive), ora
(attributed); a period (.
), which indicates an absolute value, or a percent sign (%
), which indicates percentage of total program metric; and a character string describing the metric
Note Attributed metrics can be specified for display only with thecmetrics
command, not themetrics
command, and displayed only with thecallers-callees
command, not thefunctions
command.
- TABLE 5-1 lists the available
er_print
metric keywords.Output Commands
The following commands control
er_print
output.
- Limit output to the first n entries of the report; n is an unsigned integer 1 or higher.
- Specify whether to use the long or the short form of function names (C++ only).
- Close any open output file, then open filename for subsequent output.
- If you specify a dash (
-
) instead of filename, output is written to standard output.Miscellaneous Commands
- Display address-space data for the current experiment.
- Display descriptive information about the current experiment.
- Print help information.
mapfile
load-object{
mapfilename| - }
- Write the mapfile for the specified load object to
mapfilename
. If you specify a dash (-
) instead of mapfilename,er_print
writes the mapfile to standard output.
- Write out the overview data of each of the currently selected samples.
- Exit
er_print
.
- Process additional commands from the script file script.
- Write out execution statistics, aggregated over the current sample set.
- Print the current release number of
er_print
.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |