.\"--- @(#)template.sh 1.14 90/12/06 SMI; 
'\" tep
.\" %\&Z%%\&M% %\&I% %\&E% SMI; from _source_
.TH ER_PRINT 1 "00/04/03"
.SH NAME
er_print \- print an ASCII report from Sun WorkShop performance experiments
.SH SYNOPSIS
.nf
\f3er_print\f1 [ \f3-script\fP \f2script\fP | \f3-\fP\f2command\fP | \f3-\fP ] \f2 exper_1 ... exper_n \f1
.fi
.sp 
.SH AVAILABILITY
.LP
Available with the Sun WorkShop compilers for C, C++, Fortran 77, Fortran 90,
and Assembler.
.SH DESCRIPTION
.LP
.B
\f3er_print\fP is a utility that generates an ASCII version of the various
displays supported by the
.B
Analyzer.
The output is displayed on the standard output.  Experiment files
.I exper_1 ... exper_n
are generated using the 
.B "Collector"
from the
.B "Sun WorkShop Debugging"
window, or the 
.B dbx
.I collector
command.  
Based on the data collected, various metrics of performance may be 
computed for functions, callers and callees, source files, and disassembly
listings.
The data collected, and metrics generated are described in collector(1).
The graphical displays available are described in analyzer(1).
.SH "OPTIONS"
.TP 14 
.B \-
Read \f3er_print\fP commands from the terminal.
.TP
.B \-script \f2script\f1
Read commands from the file 
.I script
which contains the commands (from the list below), one per line.
If the \f3\-script\fP argument is not present, \f3er_print\fP reads its
commands from the terminal or from the command line.
.TP
.B \-\f2command\f1
Process the given command.
.LP
Multiple options may appear on the command line, and they are processed
in the order they appear.  Scripts, \fB\-\fP arguments and explicit
commands may be mixed in any order.  If no command or script arguments
are supplied, \f3er_print\fP acts as if a \fB\-\fP argument was supplied:
it enters its interactive mode to read commands from the terminal.
.SH COMMANDS
The commands accepted by 
.B er_print
are listed below.  Any command may be abbreviated by a shorter string, as
long as the command is unambiguous.
.SS "Commands Controlling the Function List"
.TP 
.B functions 
Write the function list with current metrics.
.TP
.B metrics \f2metric_spec\f1 
Set a new current function list of metrics.
\f2metric_spec\f1 is a list of metric keywords separated by
colons.  For example,
.br
.in +5
\f3metrics i.user:i%user:e.user:e%user\fP
.in -5
means show inclusive user time, inclusive user percentage, exclusive
user time, and exclusive user percentage, in that order.
A list of all metrics available from the given experiment will be
printed in response to the \f3metric_list\fP command, described below.
.TP 
.B sort \f2metric_name\f1
Sort the function list by the given metric.  For example,
.br
.in +5
\f3sort i.user\f1
.in -5
means to sort by inclusive user time.
.TP 
.B fsummary 
Loop over the functions, and write the summary metrics panel for each.
.TP 
.B objects 
Loop over the load objects, and write each out with the current metrics.
.TP
.B osummary 
Loop over the load objects, and write the summary metrics panel for each.
.SS "Commands Controlling the Callers-Callees List"
.TP 
.B callers-callees 
Loop over the functions, as currently sorted, and write the 
.B callers-callees
panel for each, using the last 
.B cmetrics 
spec.
.TP 
.B cmetrics \f2metric_spec\f1 
Set the caller-callee metrics; similar to \f3metrics\fP,
except the \f2attribute\f1 keyword prefix \f3a\f1
is allowed in addition to \f3i\f1 or \f3e\f1.
.TP 
.B csort \f2metric_spec\f1
Sort the callers and callees within the
.B callers-callees
report for each function by the given metric.  The
.B callers-callees
report as a whole will be sorted as specified for the function list.
The \f3csort\fP metric must be either an attributed metric, or
the address or name.
.SS "Commands Controlling Source and Disassembly Listings"
.TP
.B source \f1{ \f3file\f1| \f3function\f1 } [\f2N\fP]
Write annotated source of the given file, or of the file containing
the given function.  The optional parameter, \f2N\fP, is needed
only for those cases where the \f3file\f1 or \f3function\f1 name is
ambiguous;  in that case the \f2N\fPth possible choice will be used.
When an ambiguous name is given without a numeric specifier,
a list of the possible names will be given.
In all cases, the list of names will be of object modules.
If the originally supplied name was recognized as a function, the name
of the function will be appended to the object file name.  In addition,
the number that could be used for input as the option \f2N\fP argument will
be printed.
.TP
.B disasm \f1{ \f3file \f1| \f3function\f1 } 
Write annotated disassembly of the given file, or of the file containing
the given function.  Ambiguities are resolved as with the source command,
described above.
.SS "Commands Controlling Selectivity: Samples, Threads, and LWPs"
.TP
.B sample_list 
Display the list of existing samples.
.TP 
.B sample_select \f2sample_spec\f1
\f2sample_spec\f1 is a comma separated list of single samples,
sample ranges (n-m) or both.
.TP 
.B lwp_list 
Display the list of LWP's processed during the experiment
.TP
.B lwp_select \f2lwp_spec\f1
\f2lwp_spec\f1 is a comma separated list of single LWP's,
LWP-ranges (n-m) or both.
.TP
.B thread_list 
Display the list of threads processed during the experiment
.TP 
.B thread_select \f2thread_spec\f1
\f2thread_spec\f1 is a comma separated list of single threads,
thread ranges (n-m) or both.
.TP 
.B object_list 
List the names of available load-object lists.
.TP 
.B object_select \f2obj1,obj2,...\f1
Set the list of active load objects.  The names of the objects may be
either full pathnames, or the basename.  If the name contains a comma
character, it should be surrounded by double quotes.
.SS "Commands Controlling Metrics"
.TP
.B metric_list
Display a list of metrics and the keyword names that can be used to reference
them in other commands, such as \f3sort\f1. 
Some keywords differentiate between metrics specified as a number 
(\f3e.total\f1) or as a percentage (\f3e%total\f1).
The available metrics depend on the data collected.
See the \f3collector(1)\f1 man page.
.TP
.B cmetric_list 
Display the list of metrics and keyword names for the callers-callees report.
It will appear as the metric_list output, except that attributed
metrics will appear as well.
.SS "Commands Controlling the Output"
.TP 24
.B outfile \f2filename\f1
Close any open output file, and open \f2filename\f1 for subsequent output.
If \f2filename\f1 is a dash (\-), output is written to \f3stdout\f1.
.TP
.B limit \f2n\f1
Limit any output to the first \f2n\f1 entries of the report, where \f2n\f1
is an unsigned integer.
.TP
.B name \f1{ \f3long\f1 | \f3short\f1 }
Use \f3long\f1 or \f3short\f1 form of names with C++ functions.
.SS "Miscellaneous Commands"
.TP 
.B address_space
Write the address space data.
.TP 
.B overview 
Write the current sample list, with data for each sample.
.TP 
.B statistics 
Write the execution statistics data, aggregating data over the
current sample set.
.TP
.B mapfile \f2load-object\f1 \f2mapfilename\f1 
Write the map file for the given load object to \f2mapfilename\f1. 
If \f2mapfilename\f1 is dash (-), write the map file to
.B stdout.
.TP
.B header 
Write descriptive information about the experiment.
.TP
.B script \f2script\fP
Process additional commands from the named script.
.TP
.B "help" 
Print help information.
.TP
.B "quit" 
Terminate processing and exit. No additional commands will be processed.
.TP
.B "{ Version | version }"
Print the current release version.
.SH "SEE ALSO"
.BR  analyzer(1),
.BR  collector(1),
.BR  dbx(1),
.BR  er_export(1),
.BR  er_cp(1),
.BR  er_rm(1),
.BR  er_mv(1),
.BR  workshop(1),
and
.IR "Analyzing Program Performance With Sun WorkShop".