Analyzing Program Performance with Sun WorkShop HomeContentsPreviousNextIndex

Chapter 5

er_print Reference

This 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 give er_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.

er_print is available with the Sun WorkShop compilers for C, C++, Fortran 77, and Fortran 95, and with the Assembler.

er_print Syntax

The command-line syntax for er_print is: 

er_print [-script script | -command | -] exper_1 exper_2...exper_n

Options

er_print accepts the following options:

- Read er_print commands entered at the terminal.
-script script Read 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.
-command Process 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 Commands

The 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.

functions

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.

fsummary

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.

metrics metric_spec

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:
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 available er_print metric keywords, see TABLE 5-1. To generate a listing of the keywords available for your experiment, use the metric_list or cmetric_list command.

objects

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.

osummary

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.

sort metric_keyword

Sort the function list on the specified metric. metric_keyword is one of the metrics in TABLE 5-1. For example: 

% sort i.user

This command tells er_print to sort the function list by inclusive user CPU time.

Callers-Callees List Commands

The following commands control the display of caller and callee information.

callers-callees

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   Name  

CPU sec.    CPU sec.    CPU sec.      

0.          0.010       0.010       _doprnt 

0.          0.          0.          _xflsbuf 

0.          0.010       0.         *_realbufend 

0.          0.620       0.          _rw_rdlock 

0.          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 and rw_unlock.

cmetrics metric_spec

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:
To see a listing of the currently selected metrics, use the callers-callees command.

Note – For a list of all available er_print metric keywords, see TABLE 5-1. To generate a listing of the keywords available for your experiment, use the metric_list or cmetric_list command.

csort metric_keyword

Sort the callers-callees display on the specified metric. metric_keyword is one of the keywords listed in TABLE 5-1. For example: 

% csort a.user

This command tells er_print to sort the callers-callees display by attributed user CPU time.

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.

lwp_list

Display the list of LWPs currently selected for analysis. For example: 

% lwp_list 

current: 1,3-9,17,20-38,40, total: 1-42

lwp_select lwp_spec

Select the LWPs about which you want to display information. lwp_spec is either the word all (to select all available LWPs), or a list of LWP ID numbers or ranges of ID numbers (n-m) separated by commas but no spaces. For example: 

% lwp_select 2,4,9-11,23-32,38,40

object_list

Display the list of load objects currently selected for analysis. For example: 

% object_list 

+ /home/user/a.out

+ /usr/lib/libthread.so.1

+ /usr/lib/libc.so.1

+ /usr/lib/libdl.so.1

object_select object_spec

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:

sample_list

Display the list of samples currently selected for analysis. For example: 

% sample_list 

current: 1,3-5,10,20-78, total: 1-78

sample_select sample_spec

Select the samples about which you want to display information. sample_spec is either the word all (to select all available samples), or a list of sample ID numbers or ranges of ID numbers (n-m) separated by commas but no spaces. For example: 

% sample_select 1,3-5,10,20-78

thread_list

Display the list of threads currently selected for analysis. For example: 

% thread_list 

current: 1-41, total: 1-41

thread_select thread_spec

Select the threads about which you want to display information. thread_spec is either the word all (to select all available threads), or a list of thread ID numbers or ranges of ID numbers (n-m) separated by commas but no spaces. For example: 

% thread_select all

Metric Commands

The following commands list available metric specification keywords.

metric_list

Display a list of metric keywords that you can use in other commands (for example, metrics and sort) to reference various types of metrics in the function list.
A keyword, except for the size, address, and name keywords, consists of the letter e (exclusive), i (inclusive), or a (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 the metrics command, and displayed only with the callers-callees command, not the functions command.

TABLE 5-1 lists the available er_print metric keywords.

TABLE 5-1   Metric Specification Keywords 
Absolute Value Percentage Value Description
e.user e%user Exclusive user CPU time
i.user i%user Inclusive user CPU time
a.user a%user Attributed user CPU time
e.wall e%wall Exclusive wall-clock time
i.wall i%wall Inclusive wall-clock time
a.wall a%wall Attributed wall-clock time
e.total e%total Exclusive total LWP time
i.total i%total Inclusive total LWP time
a.total a%total Attributed total LWP time
e.system e%system Exclusive system CPU time
i.system i%system Inclusive system CPU time
a.system a%system Attributed system CPU time
e.wait e%wait Exclusive system wait time
i.wait i%wait Inclusive system wait time
a.wait a%wait Attributed system wait time
e.text e%text Exclusive text-page fault time
i.text i%text Inclusive text-page fault time
a.text a%text Attributed text-page fault time
e.data e%data Exclusive data-page fault time
i.data i%data Inclusive data-page fault time
a.data a%data Attributed data-page fault time
e.sync e%sync Exclusive thread synchronization wait time
i.sync i%sync Inclusive thread synchronization wait time
a.sync a%sync Attributed thread synchronization wait time
e.syncn e%syncn Exclusive thread synchronization wait count
i.syncn i%syncn Inclusive thread synchronization wait count
a.syncn a%syncn Attributed thread synchronization wait count
size Function size, in bytes
address Address of the function in memory
name Function name


cmetric_list

Display a list of metric keywords that you can use in other commands (for example, cmetrics and csort) to reference various types of metrics in the callers-callees list.
A keyword, except for the size, address, and name keywords, consists of the letter e (exclusive), i (inclusive), or a (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 the cmetrics command, not the metrics command, and displayed only with the callers-callees command, not the functions command.

TABLE 5-1 lists the available er_print metric keywords.

Output Commands

The following commands control er_print output.

limit n

Limit output to the first n entries of the report; n is an unsigned integer 1 or higher.

name { long | short }

Specify whether to use the long or the short form of function names (C++ only).

outfile { filename | - }

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

address_space

Display address-space data for the current experiment.

header

Display descriptive information about the current experiment.

help

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.

overview

Write out the overview data of each of the currently selected samples.

quit

Exit er_print.

script script

Process additional commands from the script file script.

statistics

Write out execution statistics, aggregated over the current sample set.

{ Version | version }

Print the current release number of er_print.

Sun Microsystems, Inc.
Copyright information. All rights reserved.
Feedback
 		Library   |   Contents   |   Previous   |   Next   |   Index