Man Page er_print.1




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 aggregation 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.   The  callers-callees  metrics will
	  show the  attributed	metrics	 corresponding	to  those
	  metrics  in  the  functions  list  whose  inclusive  or
	  exclusive metrics are	shown,	as  well  as  the  static
	  metrics.

	  The dataspace	metrics	will show the  dataspace  metrics
	  for  which  data  is	available  corresponding to those
	  metrics  in  the  function  list  whose  inclusive   or
	  exclusive  metrics  are  shown,  as  well as the static
	  metrics.

	  The index objects metrics will  show	the  index-object
	  metrics  corresponding to those metrics in the function
	  list whose inclusive or exclusive metrics are	shown, as
	  well as the static metrics.

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

  Commands Governing Searching for Files
     Load object files are  first  looked  for	in  the	 archives
     directory	of  the	experiment.  If	they are not found there,
     they are looked for using the same	algorithm as  source  and
     object files, described below.

     In	most experiments, source and object files are recorded in
     the form of full paths.  In addition, Java	source files also
     have a package name, listing the directory	structure to  the
     file.   When  experiments	are  looked  at	 on  a	different
     machine, those full paths may not be accessible.

     Two complementary methods can be used to locate  source  and
     object  files:  path  mapping, and	a search path.	(The same
     methods are used for load object  files,  if  they	 are  not
     found in the archives subdirectory.)

     Path mapping is applied first, and	specifies how to  replace
     the  leading  component  in  any full file	path, with a dif-
     ferent path.  For example,	if a file is specified as:

	      /a/b/c/d/e/sourcefile

     A pathmap directive could specify mapping /a/  to	/x/y,  or
     specify mapping /a/b/c/d/ to /x, and so forth.

     If	path mapping did not find the file, the	 search	 path  is
     used.   The  search  path	gives a	list of	directories to be
     searched for a file with the given	basename (sourcefile,  in
     the example above).  The seachpath	may be set with	a setpath
     command, or may be	appended to with an addpath command.  For
     Java  files,  both	 the  package  name  and the basename are
     tried, in that order.

     Each directory in the search path is  used	 to  construct	a
     full  path	 to  try.   (Two  full paths, in the case of Java
     source files.)  Each of those full	paths will have	 pathmap-
     ping  applied to them, and	if none	of the mapped paths point
     to	the file, the next search path directory is tried.

     Finally, if neither of those mechanisms have found	the file,
     and  no  pathmapping  prefix matched the original full path,
     that original full	path is	tried.	 If  any  pathmap  prefix
     matched  the original full	path, but the file was not found,
     the original full path will not be	tried.

     Note that the default search path include the current direc-
     tory,  ., and the experiment directories, so one way to make
     source files accessible is	to copy	them to	either	of  those
     places, or	to put symbolic	links in those places pointing to
     the current location of the source	file.

     pathmap old_prefix	new_prefix
	  If a file can	not be found using 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.	A pathmap directive with no argu-
	  ments	will print the current path mapping list.

     setpath path_list
	  Set a	search path used to  find  source,  object,  etc.
	  files.   path_list  is a colon-separated list	of direc-
	  tories.  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 abbreviated with a single $ character.	 Only the
	  founder  experiment is looked	at when	searching $expts;
	  no descendant	experiments are	examined.

	  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.

     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 define others with the indxobj_define com-
     mand.

     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	Exclusive   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	 compiler   generated	functions
	  representing parallelized loops, tasks, etc.,	which are
	  aggregated with user functions in user  mode.	 In  both
	  modes,  special functions, with names	of the form <OMP-
	  *>, are shown	when the  OpenMP  runtime  is  performing
	  certain  operations  Functions  from the OpenMP runtime
	  code (libmtsk.so) are	suppressed.

	  In Machine mode, the actual native stacks  as	 captured
	  are shown.

	  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 accord-
	  ing 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

	  e[xps]    Display aggregated events from  each  experi-
		    ment

	  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,	 USTACK,  XSTACK,
     MSTACK,  LEAF,  VIRTPC,  PHYSPC, VADDR, PADDR, DOBJ, TSTAMP,
     SAMPLE, EXPID, PID, or the	name of	a memory object.  Operand
     names are case-insensitive.

     USTACK, XSTACK, MSTACK represent the function call	stacks in
     user view,	expert view, and machine view, respectively.

     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).  An additional operator ORDERED IN is for	determin-
     ing if all	elements from the left operand appear in the same
     sequence  in  the	right  operand.	 Note  that  IN	 operator
     requires all elements from	the left operand to appear in the
     right  operand but	does not enforce the order.  If-then-else
     constructs	are specified as in C, with the	?  and	:  opera-
     tors.   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 USTACK:

	  (FNAME("myfunc") SOME	IN USTACK)

     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.


  Example Filter Expressions
     To	see events from	thread 1 when it was  running  on  CPU	2
     only, use:

	THRID == 1 && CPUID == 2

     If	an index object, THRCPU, is defined as "CPUID<<16|THRID",
     the following filter is equivalent	to the one above:

	THRCPU == 0x10002

     To	filter events from experiment 2	that occurred during  the
     period between second 5 and second	9:

	EXPID==2 && TSTAMP >= 5000000000 && TSTAMP < 9000000000

     To	filter events that have	any method from	a particular Java
     class in the stack	(in user view mode):

	FNAME("myClass.*") SOME	IN USTACK

     If	function IDs are known (e.g. in	Analyzer GUI), to  filter
     events  that  contain  a  particular  call	 sequence  in the
     machine call stack:

	(314,272) ORDERED IN MSTACK

     If	the describe command lists the following properties for	a
     clock profiling experiment:

	MSTATE	  UINT32  Thread state
	NTICK	  UINT32  Duration

     then you can specify a filter to retain events in a particu-
     lar state:

	MSTATE == 1

     If	you want to filter events for duration:

	MSTATE == 1 && NTICK > 1



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 imple-
     mentation	is a prototype,	and the	functionality is expected
     to	change for the next release.



COMPATIBILITY

     er_print will only	work on	 experiments  recorded	with  the
     current  version  of the tools.  It will report an	error for
     experiments recorded with any other version.  You should 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), tha(1), regex(5), and	the  Per-
     formance Analyzer manual.