第 5 章 er_print 命令行性能分析工具

本章介绍如何使用 er_print 实用程序进行性能分析。er_print 实用程序列显性能分析器支持的各种显示的 ASCII 版本。除非将信息重定向到某个文件，否则这些信息将写入标准输出。必须为 er_print 实用程序提供由收集器生成的一个或多个实验或实验组的名称作为参数。

可以使用 er_print 实用程序显示函数或调用方和被调用方的性能度量、源代码列表和反汇编代码列表、抽样信息、数据空间数据、线程分析数据以及执行统计数据。

在多个实验或实验组上调用时，缺省情况下，er_print 将聚集实验数据，但也可用于对实验进行比较。有关更多信息，请参见compare { on | off }。

本章包含以下主题。

• er_print 语法

• 度量列表

• 控制函数列表的命令

• 控制调用方-被调用方列表的命令

• 控制调用树列表的命令

• 控制泄漏和分配列表的命令

• 控制源代码和反汇编代码列表的命令

• 控制硬件计数器数据空间和内存对象列表的命令

• 控制索引对象列表的命令

• 用于 OpenMP 索引对象的命令

• 支持线程分析器的命令

• 列出实验、样本、线程和 LWP 的命令

• 控制实验数据过滤的命令

• 控制装入对象展开和折叠的命令

• 列出度量的命令

• 控制输出的命令

• 列显其他信息的命令

• 设置缺省值的命令

• 仅为性能分析器设置缺省值的命令

• 杂项命令

• 表达式语法

• er_print 命令示例

有关收集器所收集的数据的说明，请参见第 2 章。

有关如何使用性能分析器以图形格式显示信息的说明，请参见第 4 章和联机帮助。

er_print 语法

er_print 实用程序的命令行语法如下：

er_print [ -script script | -command | - | -V ] experiment-list

er_print 实用程序的选项如下：

-

读取从键盘输入的 er_print 命令。

-script script

从文件 script 读取命令（该文件包含 er_print 命令的列表，每行一个命令）。如果 -script 选项不存在，则 er_print 从终端或从命令行读取命令。

-command [argument]

处理给定的命令。

-V

显示版本信息并退出。

多个选项可以出现在 er_print 命令行上。它们按其出现顺序进行处理。可以按任何顺序混合脚本、连字符和显式命令。未提供任何命令或脚本时的缺省操作是进入交互模式，在该模式下命令是从键盘输入的。要退出交互模式，请键入 quit 或 Ctrl-D。

处理每个命令后，会列显处理时出现的任何错误消息或警告消息。可以使用 procstats 命令列显有关处理的摘要统计数据。

在以下各节中列出了 er_print 实用程序接受的命令。

只要命令是明确的，就可以将其缩写为更短的字符串。通过以反斜杠 \ 结束行的方式可以将一个命令拆分为多行。以 \ 结尾的任何行在解析之前都会将 \ 字符删除，并追加下一行的内容。除可用内存外，对命令可使用的行数并没有限制。

必须将包含嵌入空白的参数用双引号引起来。可以将引号内的文本拆分为多行。

度量列表

许多 er_print 命令都使用度量关键字的列表。列表的语法如下：

metric-keyword-1[:metric-keyword2…]

对于动态度量（它们基于度量的数据），度量关键字包含以下三部分：度量类型字符串、度量可见性字符串和度量名称字符串。这些字符串连接在一起且没有空格，如下所示。

flavorvisibilityname

对于静态度量－它们基于实验中装入对象的静态属性（名称、地址和大小），度量关键字包含度量名称和可选的前置度量可见性字符串，两者连接在一起且没有空格：

[visibility]name

度量 flavor 和度量 visibility 字符串由类型和可见性字符组成。

表 5–1 中列出了允许的度量类型字符。包含多个类型字符的度量关键字可扩展为一系列度量关键字。例如，ie.user 可扩展为 i.user:e.user。

表 5–2 中列出了允许的度量可见性字符。可见性字符串中可见性字符的顺序无关紧要：它不影响对应度量的显示顺序。例如，i%.user 和 i.%user 都解释为 i.use:i%user。

仅可见性不同的度量始终按标准顺序一起显示。如果仅可见性不同的两个度量关键字由某些其他关键字分隔，则度量按标准顺序出现在两个度量中第一个度量的位置。

当类型字符串和可见性字符串都具有多个字符时，首先扩展类型。因此，将 ie.%user 扩展为 i.%user:e.%user，然后将其解释为 i.user:i%user:e.user:e%user。

对于静态度量，句点 (.)、加号 (+) 和百分号 (%) 这三种可见性字符在用于定义排序顺序时是等效的。因此，sort i%user、sort i.user 和 sort i+user 均表示只要包含用户 CPU 时间以任一形式可见，分析器就应该按它排序；而 sort i!user 则表示不管包含用户 CPU 时间是否可见，分析器都应该按它排序。

对于每种度量类型，可以使用叹号 (!) 可见性字符覆盖内置可见性缺省值。

如果同一度量在度量列表中出现多次，则仅处理第一次出现的该度量，而忽略随后出现的该度量。如果指定的度量不在列表中，则将它附加到列表中。

表 5–3 列出了 计时度量、同步延迟度量、内存分配度量、MPI 跟踪度量以及两个常见的硬件计数器度量的可用 er_print 度量名称字符串。对于其他硬件计数器度量，度量名称字符串与计数器名称相同。通过 metric_list 命令，可以获取已装入实验的所有可用度量名称字符串的列表。通过使用不带参数的 collect 命令，可以获取计数器名称的列表。有关硬件计数器的更多信息，请参见硬件计数器溢出分析数据。

除了表 5–3 中列出的名称字符串外，还有两个只能在缺省度量列表中使用的名称字符串。这两个名称字符串是 hwc（它与任何硬件计数器名称匹配）和 any（它与任何度量名称字符串匹配）。另请注意，cycles 和 insts 对于 SPARC 平台和 x86 平台是通用的，但是还存在特定于体系结构的其他类型的名称字符串。要列出所有可用的计数器，请使用不带参数的 collect 命令。

要查看在已装入的实验中可用的度量，请使用 metric_list 命令。

控制函数列表的命令

以下命令控制显示函数信息的方式。

functions

使用当前选定的度量写入函数列表。函数列表包括选定进行函数显示的装入对象中的所有函数，以及使用 object_select 命令隐藏其函数的任何装入对象。

可以使用 limit 命令限制写入的行数（请参见控制输出的命令）。

列显的缺省度量是独占和包含用户 CPU 时间，以秒和总程序度量百分比表示。可以使用 metrics 命令更改当前显示的度量，该命令必须在发出 functions 命令之前发出。也可以在 .er.rc 文件中使用 dmetrics 命令更改缺省值。

对于用 Java 编程语言编写的应用程序，显示的函数信息因视图模式的设置而异，视图模式可设置为用户、专家或计算机。

• 用户模式按名称显示每个方法，将已解释的方法和 HotSpot 编译的方法的数据聚集在一起；它还抑制非用户 Java 线程的数据。

• 专家模式将 HotSpot 编译的方法与已解释的方法分开，且不抑制非用户 Java 线程。

• 计算机模式在进行解释时根据 Java 虚拟机 (Java Virtual Machine, JVM) 软件显示已解释的 Java 方法的数据，并对指定的方法报告使用 Java HotSpot 虚拟机编译的方法的数据。显示所有线程。

在所有三种模式下，对于 Java 目标调用的任何 C、C++ 或 Fortran 代码，都以通用的方法报告数据。

metrics metric_spec

指定函数列表度量的选项。字符串 metric_spec 可以是恢复缺省度量选项的关键字 default，也可以是由冒号分隔的一系列度量关键字。以下示例说明一个度量列表。

% metrics i.user:i%user:e.user:e%user

此命令指示 er_print 实用程序显示以下度量：

• 用秒表示的包含用户 CPU 时间

• 包含用户 CPU 时间百分比

• 用秒表示的独占用户 CPU 时间

• 独占用户 CPU 时间百分比

缺省情况下，所用的度量设置基于从 .er.rc 文件处理的 dmetrics 命令，如设置缺省值的命令中所述。如果 metrics 命令将 metric_spec 显式设置为 default，则根据所记录的数据恢复缺省设置。

重置度量时，会在新列表中设置缺省排序度量。

如果省略 metric_spec，则显示当前的度量设置。

除了设置函数列表的度量外，metrics 命令还将调用方-被调用方的度量以及数据派生输出的度量设为相同的设置。

处理 metrics 命令时，将列显一条消息，指明当前的度量选项。对于前面的示例，消息如下。

current: i.user:i%user:e.user:e%user:name

有关度量列表的语法的信息，请参见度量列表。要查看可用度量的列表，请使用 metric_list 命令。

如果 metrics 命令中包含错误，则忽略该命令并显示一条警告，但先前的设置仍然有效。

sort metric_spec

按 metric_spec 对函数列表进行排序。度量名称中的 visibility 不影响排序顺序。如果在 metric_spec 中指定了多个度量，则使用第一个可见度量。如果指定的度量都不可见，则忽略该命令。可以在 metric_spec 前加上减号 (-) 以指定反向排序。

缺省情况下，度量排序设置基于从 .er.rc 文件处理的 dsort 命令，如设置缺省值的命令中所述。如果 sort 命令将 metric_spec 显式设置为 default，则使用缺省设置。

字符串 metric_spec 为度量列表中所述的度量关键字之一，如以下示例所示。

% sort i.user

此命令指示 er_print 实用程序按包含用户 CPU 时间对函数列表进行排序。如果度量不在已装入的实验中，则列显一条警告并忽略该命令。完成命令时，将列显排序度量。

fsummary

为函数列表中的每个函数写入摘要面板。可以使用 limit 命令限制写入的面板数（请参见控制输出的命令）。

摘要度量面板包括函数或装入对象的名称、地址和大小（对于函数，还包括源文件、目标文件和装入对象的名称），以及选定函数或装入对象的所有记录的度量（包括以值和百分比形式表示的独占和包含度量）。

fsingle function_name [N]

为指定的函数写入摘要面板。当有多个函数具有相同的名称时，需要使用可选参数 N。为具有给定函数名称的第 N 个函数写入摘要度量面板。在命令行上提供命令时，N 是必需的；如果不需要它，则将其忽略。当以交互方式提供不带 N 的命令但又需要 N 时，则会列显具有对应 N 值的函数列表。

有关函数的摘要度量的说明，请参见对 fsummary 命令的描述。

控制调用方-被调用方列表的命令

以下命令控制显示调用方和被调用方信息的方式。

callers-callees

按函数排序度量 (sort) 指定的顺序，输出每个函数的调用方-被调用方面板。

在每个调用方-被调用方报告中，调用方和被调用方按调用方-被调用方排序度量 (csort) 进行排序。可以使用 limit 命令限制写入的面板数（请参见控制输出的命令）。选定的（中央）函数以星号标记，如以下示例所示。

Attr.     Excl.     Incl.      Name
User CPU  User CPU  User CPU
 sec.      sec.       sec.
4.440     0.        42.910     commandline
0.        0.         4.440    *gpf
4.080     0.         4.080     gpf_b
0.360     0.         0.360     gpf_a

在此示例中，gpf 是选定的函数；它由 commandline 调用，而它调用 gpf_a 和 gpf_b。

csingle function_name [N]

为指定的函数写入调用方-被调用方面板。当有多个函数具有相同的名称时，需要使用可选参数 N。为具有给定函数名称的第 N 个函数写入调用方-被调用方面板。在命令行上提供命令时，N 是必需的；如果不需要它，则将其忽略。当以交互方式提供不带 N 的命令但又需要 N 时，则会列显具有对应 N 值的函数列表。

cprepend function-name [N | ADDR]

构建调用堆栈时，将指定的函数置于当前调用堆栈片段之前。如果函数名称不明确，可选参数是必需的；有关指定该参数的更多信息，请参见source|src { filename | function_name } [ N]。

cappend function-name [N | ADDR]

构建调用堆栈时，将指定函数附加到当前调用堆栈片段。如果函数名称不明确，可选参数是必需的；有关指定该参数的更多信息，请参见source|src { filename | function_name } [ N]。

crmfirst

构建调用堆栈时，从调用堆栈片段删除顶部帧。

crmlast

构建调用堆栈时，从调用堆栈片段删除底部帧。

控制调用树列表的命令

本节介绍用于调用树的命令。

calltree

显示来自实验的动态调用图，显示每个级别的分层度量。

控制泄漏和分配列表的命令

本节介绍与内存分配和解除分配相关的命令。

leaks

显示由通用调用栈聚集的内存泄漏列表。每个条目显示了总泄漏数和给定调用栈的总泄漏字节数。该列表按泄漏的字节数进行排序。

allocs

显示由通用调用栈聚集的内存分配列表。每个条目显示了分配数和给定调用栈的总分配字节数。该列表按分配的字节数进行排序。

控制源代码和反汇编代码列表的命令

以下命令控制显示带注释的源代码和反汇编代码的方式。

pcs

写入程序计数器 (program counter, PC) 及其度量的列表（按当前排序度量排序）。该列表包括为使用 object_select 命令隐藏其函数的每个装入对象显示聚集度量的行。

psummary

按当前排序度量指定的顺序，为 PC 列表中的每个 PC 写入摘要度量面板。

lines

写入源代码行及其度量的列表（按当前排序度量排序）。该列表包括为没有行号信息或其源文件未知的每个函数显示聚集度量的行，以及为使用 object_select 命令隐藏其函数的每个装入对象显示聚集度量的行。

lsummary

按当前排序度量指定的顺序，为行列表中的每个行写入摘要度量面板。

source|src { filename | function_name } [ N]

为指定文件或包含指定函数的文件写出带注释的源代码。在任一情况下该文件都必须位于您所指定的路径中的目录下。如果使用 GNU Fortran 编译器编译了源代码，则函数名称出现在源代码中时，必须在其后添加两个下划线字符。

仅当文件或函数的名称不明确时，才使用可选参数 N（正整数）；在这种情况下，使用第 N 个可能的选项。如果提供不带数字说明符的不明确名称，则 er_print 实用程序将列显可能的目标文件名称的列表；如果提供的名称是函数，则将函数名称附加到目标文件名称，还将列显表示该目标文件的 N 值的数字。

也可以将函数名称指定为 function"file"，其中 file 用于指定函数的替代源上下文。紧邻第一个指令之后，将添加函数的索引行。索引行显示为尖括号内的文本，其格式如下：

<Function: f_name>

任何函数的缺省源上下文都被定义为该函数的第一条指令所归属的源文件。它通常是经过编译而生成包含该函数的目标模块的源文件。替代源上下文由包含归属于该函数的指令的其他文件组成。此类上下文包括来自头文件的指令和来自内联到指定函数中的函数的指令。如果存在任何替代源上下文，则在缺省源上下文的开头包括扩展索引行的列表以指示替代源上下文所在的位置，格式如下：

<Function: f, instructions from source file src.h>

如果在命令行上调用 er_print 实用程序时使用了 -source 参数，则必须在 file 引号前加上反斜杠转义符。换句话说，函数名称的格式为 function\"file\"。当 er_print 实用程序处于交互模式时，反斜杠不是必需的，也不应使用它。

通常，在使用缺省源上下文时，会显示该文件中所有函数的度量。如果显式引用该文件，则仅显示指定函数的度量。

disasm|dis { filename | function_name } [ N]

为指定文件或包含指定函数的文件写出带注释的反汇编代码。该文件必须位于您所指定的路径中的目录下。

可选参数 N 与 source 命令的可选参数的使用方法相同。

scc com_spec

指定在带注释的源代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表，包含零个或多个以下消息类。

类 all 和 none 不能与其他类一起使用。

如果未提供 scc 命令，则显示的缺省类为 basic。如果提供了 scc 命令，但 class-list 为空，则关闭编译器注释。scc 命令通常仅在 .er.rc 文件中使用。

sthresh value

指定带注释的源代码中突出显示度量的阈值百分比。对于文件中的任何源代码行，如果任何度量的值等于或大于该度量最大值的 value %，则在该度量所在行的开头插入 ##。

dcc com_spec

指定在带注释的反汇编代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表。可用类的列表与表 5–4 中所示的带注释的源代码列表的类列表相同。可以在类列表中添加以下选项。

dthresh value

指定带注释的反汇编代码中突出显示度量的阈值百分比。对于文件中的任何指令行，如果任何度量的值等于或大于该度量最大值的 value %，则在该度量所在行的开头插入 ##。

cc com_spec

指定在带注释的源代码和反汇编代码列表中显示的编译器注释的类。类列表是类的冒号分隔列表。可用类的列表与表 5–4 中所示的带注释的源代码列表的类列表相同。

setpath path_list

设置用于查找源文件和目标文件的路径。path_list 是目录的冒号分隔列表。如果任何目录中包含冒号字符，请用反斜杠将它转义。特殊目录名称 $expts 引用当前实验集（按装入实验的顺序）；可以将其缩写为单个 $ 字符。

缺省设置为：$expts:.。如果在搜索当前路径设置时未找到文件，则使用编译时的全路径名。

不带参数的 setpath 列显当前路径。

addpath path_list

将 path_list 附加到当前 setpath 设置。

pathmap old-prefix new-prefix

如果使用由 addpath 或 setpath 设置的 path_list 找不到文件，则可以使用 pathmap 命令指定一个或多个路径重映射。在以 old-prefix 所指定的前缀开头的源文件、目标文件或共享对象的任何路径名中，旧的前缀将由 new-prefix 所指定的前缀替代。然后，使用所得到的路径查找文件。可采用多个 pathmap 命令，并逐一尝试，直到找到文件为止。

控制硬件计数器数据空间和内存对象列表的命令

对于利用硬件计数器分析和数据空间分析收集的实验，可以查看与以下内容相关的度量：

• 数据对象－程序常量、变量、数组和聚集（如结构和联合），以及源代码中所述的各种聚集元素。

• 内存对象－内存子系统中的组件，如高速缓存行、页面和内存区。对象是通过从所记录的虚拟地址或物理地址计算的索引确定的。为虚拟页面和物理页面预定义了内存对象，其大小为 8KB、64KB、512KB 和 4 MB。可以利用 mobj_define 命令定义其他内存对象。

此数据只能在利用 SPARC 体系结构上的 -xhwcprof 编译器选项编译的 Solaris 对象上进行收集。

有关这些类型数据的更多信息，请参见硬件计数器溢出分析数据。有关用于执行硬件计数器溢出分析的命令行的信息，请参见-h counter_definition_1...[, counter_definition_n]。

有关 -xhwcprof 选项的信息，请参见《Oracle Solaris Studio 12.2：Fortran 用户指南》、《Oracle Solaris Studio 12.2：C 用户指南》或《Oracle Solaris Studio 12.2：C++ 用户指南》。

data_objects

写入数据对象及其度量的列表。

data_single name [N]

写入指定数据对象的摘要度量面板。在对象名称不明确的情况下，需要使用可选参数 N。当指令在命令行上时，N 是必需的；如果不需要它，则将其忽略。

data_layout

为具有数据派生度量数据的所有程序数据对象写入带注释的数据对象布局，按整个结构的当前数据排序度量值排序。每个聚集数据对象会显示归属于该对象的总度量，后跟按偏移顺序显示的所有元素，每个元素具有自己的度量和相对于 32 字节块的大小和位置指示符。

memobj mobj_type

使用当前度量写入给定类型的内存对象的列表。所用度量和排序方式与数据空间列表相同。还可以将名称 mobj_type 直接用作命令。

mobj_list

写入已知类型的内存对象的列表，用法与 memobj 命令中的 mobj_type 相同。

mobj_define mobj_type index_exp

通过将 VA/PA 映射到由 index_exp 提供的对象，定义新的内存对象类型。表达式的语法在表达式语法中介绍。

不应先定义 mobj_type。其名称必须完全由字母数字字符或 "_" 字符组成，且以字母字符开头。

index_exp 必须在语法上是正确的。如果它在语法上不正确，则将返回错误并忽略定义。

<Unknown> 内存对象的索引是 -1，而且用于定义新内存对象的表达式应该支持识别 <Unknown>。例如，对于基于 VADDR 的对象，表达式应该采用以下格式：

VADDR>255?expression :-1

而对于基于 PADDR 的对象，表达式应该采用以下格式：

PADDR>0?expression:-1

控制索引对象列表的命令

索引对象命令适用于所有实验。索引对象列表是可以从所记录的数据计算其索引的对象的列表。为线程、CPU、样本和秒预定义了索引对象。可以使用 indxobj_define 命令定义其他索引对象。

以下命令控制索引对象列表。

indxobj indxobj_type

写入与给定类型匹配的索引对象及其度量的列表。索引对象的度量和排序方式与函数列表相同，只不过仅包含独占度量。也可以将名称 indxobj_type 直接用作命令。

indxobj_list

写入已知类型的索引对象的列表，用法与 indxobj 命令中的 indxobj_type 相同。

indxobj_define indxobj_type index_exp

通过将包映射到由 index_exp 提供的对象，定义新的索引对象类型。表达式的语法在表达式语法中介绍。

不应先定义 indxobj_type。其名称不区分大小写，必须完全由字母数字字符或 "_" 字符组成，且以字母字符开头。

index_exp 必须在语法上是正确的，否则将返回错误并忽略定义。如果 index_exp 包含任何空格，则必须用双引号 (") 将其引起来。

<Unknown> 索引对象的索引是 -1，而且用于定义新索引对象的表达式应该支持识别 <Unknown>。

例如，对于基于虚拟或物理 PC 的索引对象，表达式应该采用以下格式：

VIRTPC>0?VIRTPC:-1

用于 OpenMP 索引对象的命令

可以使用以下命令列显有关 OpenMP 索引对象的信息。

OMP_preg

列显在实验中执行的 OpenMP 并行区域及其度量的列表。此命令仅可用于含有 OpenMP 3.0 性能数据的实验。

OMP_task

列显在实验中执行的 OpenMP 任务及其度量的列表。此命令仅可用于含有 OpenMP 3.0 性能数据的实验。

支持线程分析器的命令

以下命令支持线程分析器。有关捕获和显示的数据的更多信息，请参见《Oracle Solaris Studio 12.2：线程分析器用户指南》。

races

将所有数据争用的列表写入实验中。数据争用报告只能从具有数据争用检测数据的实验获得。

rdetail race_id

写入给定 race_id 的详细信息。如果 race_id 设置为 all，显示所有数据争用的详细信息。数据争用报告只能从具有数据争用检测数据的实验获得。

deadlocks

写入实验中检测到的所有实际死锁和潜在死锁的列表。死锁报告只能从具有死锁检测数据的实验获得。

ddetail deadlock_id

写入给定 deadlock_id 的详细信息。如果 deadlock_id 设置为 all，则显示所有死锁的详细信息。死锁报告只能从具有死锁检测数据的实验获得。

列出实验、样本、线程和 LWP 的命令

本节介绍列出实验、样本、线程和 LWP 的命令。

experiment_list

显示装入的实验及其 ID 号的完整列表。列出的每个实验都有一个索引（在选择样本、线程或 LWP 时使用）和一个 PID（可在高级过滤时使用）。

以下示例显示一个实验列表。

(er_print) experiment_list
ID Experiment
== ==========
1 test.1.er
2 test.6.er

sample_list

显示当前选定的要进行分析的样本列表。

以下示例显示一个样本列表。

(er_print) sample_list
Exp Sel     Total
=== ======= =====
  1 1-6        31
  2 7-10,15    31

lwp_list

显示当前选定的要进行分析的 LWP 的列表。

thread_list

显示当前选定的要进行分析的线程的列表。

cpu_list

显示当前选定的要进行分析的 CPU 的列表。

控制实验数据过滤的命令

可以指定按以下两种方式过滤实验数据：

• 指定过滤表达式，为每个数据记录计算该表达式以确定是否应该包括该记录

• 选择要进行过滤的实验、样本、线程、CPU 和 LWP

指定过滤表达式

可以使用 filters 命令指定过滤表达式。

filters filter_exp

filter_exp 是一个表达式，对于应该包括的任何数据记录，其计算结果为真；对于不应包括的记录，其计算结果为假。表达式的语法在表达式语法中介绍。

列出过滤器表达式的操作数令牌

可查看可在相关实验上的过滤器表达式中使用的操作数列表。

describe

输出可用于构建过滤器表达式的令牌列表。表达式语法中对过滤器表达式的某些令牌和语法进行了描述。

选择要进行过滤的样本、线程、LWP 和 CPU

选择列表

选择语法如以下示例所示。该语法用于命令描述。

[experiment-list:]selection-list[+[
experiment-list:]selection-list … ]

可以在每个选择列表前面加上实验列表，用冒号与其隔开且不加空格。可以通过用 + 符号连接多个选择列表来进行多个选择。

实验列表和选择列表具有相同的语法，可以使用关键字 all，也可以使用编号或编号范围 (n-m) 的列表，其中用逗号分隔且不加空格，如以下示例所示。

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

可以使用 experiment_list 命令确定实验编号。

一些选择示例如下所示。

1:1-4+2:5,6
all:1,3-6

在第一个示例中，从实验 1 选择了对象 1 到 4，从实验 2 选择了对象 5 和 6。在第二个示例中，从所有实验选择了对象 1 以及 3 到 6。对象可以是 LWP、线程或样本。

选择命令

用于选择 LWP、样本、CPU 和线程的命令不是独立的。如果某个命令的实验列表与前一个命令的实验列表不同，则按以下方式将来自最后一个命令的实验列表应用于所有三个选择目标－LWP、样本和线程。

• 关闭不在最后一个实验列表中的实验的现有选择。

• 保留最后一个实验列表中的实验的现有选择。

• 对于没有做出任何选择的目标，将选择设置为 all。

sample_select sample_spec

选择要显示其信息的样本。命令完成时，会显示所选样本的列表。

lwp_select lwp_spec

选择要显示其信息的 LWP。命令完成时，会显示所选 LWP 的列表。

thread_select thread_spec

选择要显示其信息的线程。命令完成时，会显示所选线程的列表。

cpu_select cpu_spec

选择要显示其信息的 CPU。命令完成时，会显示所选 CPU 的列表。

控制装入对象展开和折叠的命令

这些命令确定 er_print 实用程序显示装入对象的方式。

object_list

显示一个由两列组成的列表，包含全部装入对象的状态和名称。在第一列中显示每个装入对象的显示/隐藏/API 状态，在第二列中显示对象的名称。每个装入对象名称前有 show（指示在函数列表中显示该对象的函数（已展开））、hide（指示在函数列表中不显示该对象的函数（已折叠））或 API-only（如果仅显示那些代表装入对象入口点的函数）。已折叠装入对象的所有函数都映射到函数列表中表示整个装入对象的单个条目。

以下是装入对象列表的示例。

(er_print) object_list
Sel  Load Object
==== ==================
hide <Unknown>
show <Freeway>
show <libCstd_isa.so.1>
show <libnsl.so.1>
show <libmp.so.2>
show <libc.so.1>
show <libICE.so.6>
show <libSM.so.6>
show <libm.so.1>
show <libCstd.so.1>
show <libX11.so.4>
show <libXext.so.0>
show <libCrun.so.1>
show <libXt.so.4>
show <libXm.so.4>
show <libsocket.so.1>
show <libgen.so.1>
show <libcollector.so>
show <libc_psr.so.1>
show <ld.so.1>
show <liblayout.so.1>

object_show object1,object2,...

设置所有已命名的装人对象以显示其所有函数。对象的名称可以为全路径名或基本名称。如果名称包含逗号字符，则必须用双引号将名称引起来。如果使用字符串 "all" 命名装入对象，则显示所有装入对象的函数。

object_hide object1,object2,...

设置所有已命名的装人对象以隐藏其所有函数。对象的名称可以为全路径名或基本名称。如果名称包含逗号字符，则必须用双引号将名称引起来。如果使用字符串 "all" 命名装入对象，则显示所有装入对象的函数。

object_api object1,object2,...

设置所有已命名的装人对象以仅显示所有代表库入口点的函数。对象的名称可以为全路径名或基本名称。如果名称包含逗号字符，则必须用双引号将名称引起来。如果使用字符串 "all" 命名装入对象，则显示所有装入对象的函数。

objects_default

按照 .er.rc 文件配置中的初始缺省值设置所有装入对象。

object_select object1,object2,...

选择要显示有关其中函数信息的装入对象。显示所有已命名的装入对象的函数，隐藏所有其他装入对象的函数。object-list 是装入对象的列表，用逗号分隔且不加空格。如果显示某个装入对象的函数，则在函数列表中显示具有非零度量的所有函数。如果隐藏某个装入对象的函数，则会折叠其函数，并且仅显示包含整个装入对象的度量的单个行，而不是显示其各个函数。

装入对象的名称应该为全路径名或基本名称。如果对象名称本身包含逗号，则必须用双引号将名称引起来。

列出度量的命令

以下命令列出当前选定的度量以及所有可用的度量关键字。

metric_list

显示函数列表中当前选定的度量和可以在其他命令（例如 metrics 和 sort）中使用的度量关键字列表，以在函数列表中引用各种类型的度量。

cmetric_list

显示当前选定的调用方-被调用方度量以及调用方-被调用方报告的度量和关键字名称的列表。以与 metric_list 输出相同的方式显示列表，但是同时包括归属度量。

data_metric_list

显示当前选定的数据派生度量以及所有数据派生报告的度量和关键字名称的列表。列表的显示方式与 metric_list 命令的输出方式相同，但是仅包括那些具有数据派生类型的度量和静态度量。

indx_metric_list

显示当前选定的索引对象度量以及所有索引对象报告的度量和关键字名称的列表。以与 metric_list 命令相同的方式显示列表，但是仅包括那些具有独占类型的度量和静态度量。

控制输出的命令

以下命令控制 er_print 显示输出。

outfile { filename | - }

关闭任何打开的输出文件，然后为后续输出打开 filename。打开 filename 时，将清除任何先前存在的内容。如果指定一个短划线 (-) 而不是 filename，则将输出写入标准输出。如果指定两个短划线 (--) 而不是 filename，则将输出写入标准错误。

appendfile filename

关闭任何打开的输出文件并打开 filename，保留任何先前存在的内容，以便将后续输出附加到文件的结尾。如果 filename 不存在，则 appendfile 命令的功能与 outfile 命令的功能相同。

limit n

将输出限制为报告中的前 n 个条目；n 是一个无符号正整数。

name { long | short } [ :{ shared_object_name | no_shared_object_name } ]

指定是使用长形式还是短形式的函数名称（仅限 C++ 和 Java）。如果指定了 shared_object_name，则将共享对象名称附加到函数名称。

viewmode { user| expert | machine }

将模式设置为以下模式之一：

user（用户）

对于 Java 实验，显示 Java 线程的 Java 调用栈，而不显示内务处理线程。函数列表包括函数 <JVM-System>，该函数表示来自非 Java 线程的聚集时间。当 JVM 软件不报告 Java 调用栈时，将根据函数 <no Java callstack recorded> 报告时间。

对于 OpenMP 实验，显示重构的调用栈，这些重构的调用栈类似于在不使用 OpenMP 的情况下编译程序时获取的调用栈。在 OpenMP 运行时执行某些操作时，添加名称格式为 <OMP-*> 的特殊函数。

expert（专家）

对于 Java 实验，在执行用户的 Java 代码时，将显示 Java 线程的 Java 调用栈，而在执行 JVM 代码或当 JVM 软件不报告 Java 调用栈时，则显示计算机调用栈。显示内务处理线程的计算机调用栈。

对于 OpenMP 实验，显示编译器生成的、代表并行化循环、任务等的函数，这些函数会与用户模式中的用户函数聚集。在 OpenMP 运行时执行某些操作时，添加名称格式为 <OMP-*> 的特殊函数。

machine（计算机）

对于 Java 实验和 OpenMP 实验，显示所有线程的计算机调用栈。

对于除 Java 实验和 OpenMP 实验之外的所有实验，所有三种模式都显示相同的数据。

compare { on | off }

将比较模式设置为打开或关闭。缺省值是关闭，因此在读取同一个可执行文件上的多个实验时，会聚集数据。如果通过在 .er.rc 文件中设置 compare on 启用比较模式，且在同一个可执行文件上装入了多个实验，就会针对来自每个实验的数据分别显示度量列。此外，还可以使用 er_print compare 命令比较实验。

在比较模式下，在“函数”列表、“调用方-被调用方”列表以及“源和反汇编”列表上的相邻列中显示来自实验或组的数据。这些列按装入实验或组的顺序显示，同时带有一个给出实验或组名称的附加标题行。

列显其他信息的命令

以下 er_print 子命令显示关于该实验的其他信息。

header exp_id

显示有关指定实验的描述性信息。exp_id 可以通过 exp_list 命令获得。如果 exp_id 为 all 或未提供，则显示所有已装入实验的信息。

在每个标头后，将列显任何错误或警告。每个实验的标头由一行短划线分隔。

如果实验目录包含名为 notes 的文件，则将该文件的内容添加到标头信息之前。可以通过 collect 命令的 -C "comment" 参数，手动添加、编辑或指定 notes 文件。

exp_id 在命令行上是必需的，但是在脚本中或交互模式下不是必需的。

ifreq

从度量的计数数据写入指令频率列表。指令频率报告只能从计数数据生成。此命令仅在运行 Solaris OS 的 SPARC 处理器上适用。

objects

列出装入对象以及由于使用装入对象而产生的任何错误或警告消息以用于性能分析。可以使用 limit 命令限制列出的装入对象数（请参见控制输出的命令）。

overview exp_id

写出当前为指定实验选择的每个样本的样本数据。exp_id 可以通过 exp_list 命令获得。如果 exp_id 为 all 或未提供，则显示所有实验的样本数据。exp_id 在命令行上是必需的，但是在脚本中或交互模式下不是必需的。

statistics exp_id

写出在指定实验的当前样本集上聚集的执行统计数据。有关显示的执行统计数据的定义和含义的信息，请参见 getrusage(3C) 和 proc(4) 手册页。执行统计数据包括来自收集器未收集其任何数据的系统线程的统计数据。

exp_id 可以通过 experiment_list 命令获得。如果未提供 exp_id，则显示在每个实验的样本集上聚集的所有实验的数据总和。如果 exp_id 为 all，则显示每个实验的总和统计和单独统计。

设置缺省值的命令

可以在 .er.rc 文件中使用以下命令为 er_print、er_src 和性能分析器设置缺省值。这些命令只能用于设置缺省值：它们不能用作 er_print 实用程序的输入。只能将这些命令包括在名为 .er.rc 的缺省值文件中。仅适用于性能分析器缺省值的命令在仅为性能分析器设置缺省值的命令中介绍。有关分析器如何使用 .er.rc 文件的信息，请参见分析器缺省设置。

可将 .er.rc 缺省值文件包含在主目录中以为所有实验设置缺省值，或者将其包含在任何其他目录中以在本地设置缺省值。启动 er_print 实用程序、er_src 实用程序或性能分析器时，将扫描当前目录和主目录以查找 .er.rc 文件。如果存在这些文件，就读取它们，同时还读取系统缺省值文件。您的主目录中的 .er.rc 文件的缺省值覆盖系统缺省值，当前目录中的 .er.rc 文件的缺省值覆盖主目录缺省值和系统缺省值。

要确保从存储实验的目录读取缺省值文件，必须从该目录启动性能分析器或 er_print 实用程序。

缺省值文件还可以包括 scc、sthresh、dcc、dthresh、cc、setpath、addpath、pathmap、name、mobj_define、object_show、object_hide、object_api、indxobj_define、tabs、rtabs 和 viewmode 命令。可以在缺省值文件中包括多个 dmetrics、dsort、addpath、pathmap、mobj_define 和 indxobj_define 命令，并串联来自所有 .er.rc 文件的命令。对于所有其他命令，如果出现多次，则使用第一次出现的该命令，而忽略随后出现的该命令。

dmetrics metric_spec

指定要在函数列表中显示或列显的缺省度量。度量列表的语法和用法在度量列表一节中介绍。列表中度量关键字的顺序确定显示度量的顺序和它们在性能分析器的度量选择器中出现的顺序。

可通过在列表中每个度量名称第一次出现之前添加对应的归属度量，从函数列表缺省度量派生调用方-被调用方列表的缺省度量。

dsort metric_spec

指定函数列表将按其排序的缺省度量。排序度量是该列表中与任何已装入实验中的度量匹配的第一个度量，且受到以下条件的限制：

• 如果 metric_spec 中的条目具有叹号 ! 可见性字符串，则使用其名称匹配的第一个度量，而不管它是否可见。

• 如果 metric_spec 中的条目具有任何其他可见性字符串，则使用其名称匹配的第一个可见度量。

度量列表的语法和用法在度量列表一节中介绍。

调用方-被调用方列表的缺省排序度量是对应于函数列表的缺省排序度量的归属度量。

en_desc { on | off | =regexp }

将读取后续实验的模式设置为 on（启用所有后续实验）或 off（禁用所有后续实验）。如果使用 =regexp，则启用其沿袭或可执行文件名称与正则表达式匹配的那些实验的数据。缺省设置是 on，即跟踪所有子孙进程。

仅为性能分析器设置缺省值的命令

可以在 .er.rc 文件中使用以下命令为性能分析器设置一些其他缺省值。

tabs tab_spec

设置在分析器中可见的一组缺省标签。标签由生成对应报告的 er_print 命令命名（包括用于内存对象标签的 mobj_type 或用于索引对象标签的 indxobj_type）。mpi_timeline 指定“MPI 时间线”标签，mpi_chart 指定“MPI 图表”标签，timeline 指定“时间线”标签，而 headers 指定“实验”标签。

仅显示已装入实验中的数据所支持的那些标签。

rtabs tab_spec

设置使用 tha 命令调用分析器时可见的一组缺省标签，以便检查线程分析器实验。仅显示已装入实验中的数据所支持的那些标签。

tlmode tl_mode

设置性能分析器的“时间线”标签的显示模式选项。选项列表是一个冒号分隔列表。下表介绍了允许的选项。

选项 lwp、thread 和 cpu 是互斥的，root 和 leaf 也是互斥的。如果在列表中包括一组互斥选项中的多个选项，则仅使用最后一个选项。

tldata tl_data

选择在性能分析器的“时间线”标签中显示的缺省数据类型。类型列表中的类型由冒号分隔。下表列出了允许的类型。

杂项命令

可在 er_print 实用程序中使用以下命令执行其他任务。

procstats

列显处理数据的累积统计数据。

script file

处理脚本文件 file 中的附加命令。

version

列显 er_print 实用程序的当前版本号。

quit

终止当前脚本的处理，或者退出交互模式。

help

列显 er_print 命令的列表。

表达式语法

定义过滤器的表达式和用于计算内存对象索引的表达式使用通用语法。

语法将表达式指定为运算符和操作数的组合。对于过滤器，如果表达式的计算结果为真，则包括包；如果表达式的计算结果为假，则排除包。对于内存对象或索引对象，表达式的计算结果为一个索引，该索引定义包中引用的特定内存对象或索引对象。

表达式中的操作数或者是常量或者是数据记录中的字段，如使用 describe 命令的执行结果所示。这些操作数包括 THRID、LWPID、CPUID、USTACK、XSTACK、MSTACK、LEAF、VIRTPC、PHYSPC、VADDR、PADDR、DOBJ、TSTAMP、SAMPLE、EXPID、PID 或内存对象的名称。操作数名称不区分大小写。

USTACK、XSTACK 和 MSTACK 分别表示用户视图、专家视图和计算机视图中的函数调用堆栈。

仅当为硬件计数器分析或时钟分析指定 "+" 时，VIRTPC、PHYSPC、VADDR 和 PADDR 都不为零。此外，当无法确定实际虚拟地址时，VADDR 小于 256。如果无法确定 VADDR 或者无法将虚拟地址映射到物理地址，PADDR 为零。同样，如果回溯失败或者未请求回溯， VIRTPC 为零；如果 VIRTPC 为零或者无法将 VIRTPC 映射到物理地址，PHYSPC 为零。

运算符包括常见的逻辑运算符和算术（包括移位）运算符（在 C 表示法中，具有 C 优先级规则），以及用于确定某个元素是否位于集中的运算符 (IN) 或用于确定某组元素中的任一元素或全部元素是否包含在集中的运算符（分别对应 SOME IN 或 IN）。附加运算符 ORDERED IN 用于确定左侧操作数中的所有元素是否以相同的顺序出现在右侧操作数中。注意，IN 运算符要求左侧操作数中的所有元素出现在右侧操作数中，但对顺序未作要求。如在 C 中那样指定 If-then-else 结构（使用 ? 和 : 运算符）。使用圆括号以确保正确解析所有表达式。在 er_print 命令行上，不能将表达式拆分为多行。在脚本中或命令行上，如果表达式包含空格，则必须用双引号将其引起来。

过滤表达式的计算结果为布尔值。如果应该包括包，则计算结果为真，如果不应该包括包，则计算结果为假。线程、LWP、CPU、实验 id、进程 pid 和样本过滤基于相应关键字和整数之间的关系表达式，或者使用 IN 运算符和逗号分隔的整数列表。

可通过在 TSTAMP 和时间（以整数纳秒为单位，从将要处理其包的实验开始时算起）之间指定一个或多个关系表达式来使用时间过滤。样本的时间可以使用 overview 命令获得。overview 命令中的时间以秒为单位，必须转换为纳秒以用于时间过滤。时间还可以从分析器中的“时间线”显示获得。

函数过滤可以基于叶函数或栈中的任何函数。按叶函数进行过滤是通过 LEAF 关键字和整型函数 id 之间的关系表达式指定的，或者使用 IN 运算符和结构 FNAME("regexp") 指定，其中 regexp 是正则表达式，如 regexp(5) 手册页中所指定的那样。函数的整个名称（如 name 的当前设置所指定）必须匹配。

可以通过确定构造 FNAME(“regexp ”) 中的任何函数是否位于由关键字 USTACK: (FNAME(“myfunc”) SOME IN USTACK) 表示的函数数组中来指定基于调用堆栈中的任何函数的过滤。

数据对象过滤类似于栈函数过滤，使用 DOBJ 关键字和结构 DNAME("regexp")（括在圆括号中）。

内存对象过滤是使用内存对象的名称（如 mobj_list 命令中所示）和对象的整型索引或对象集的索引来指定的。（<Unknown> 内存对象的索引是 -1。）

索引对象过滤是使用索引对象的名称（如 indxobj_list 命令中所示）和对象的整型索引或对象集的索引来指定的。（<Unknown> 索引对象的索引是 -1。）

数据对象过滤和内存对象过滤仅对具有数据空间数据的硬件计数器包有意义；此类过滤将排除所有其他包。

虚拟地址或物理地址的直接过滤是通过 VADDR 或 PADDR 与地址之间的关系表达式指定的。

内存对象定义（请参见mobj_define mobj_type index_exp）使用其计算结果为整型索引的表达式（使用 VADDR 关键字或 PADDR 关键字）。该定义仅适用于内存计数器和数据空间数据的硬件计数器包。该表达式应该返回整数，对于 <Unknown> 内存对象，则返回 -1。

索引对象定义（请参见indxobj_define indxobj_type index_exp）使用其计算结果为整型索引的表达式。该表达式应该返回整数，对于 <Unknown> 索引对象，则返回 -1。

示例过滤器表达式

本节介绍可通过 er_print -filters 命令以及在分析器过滤对话框中使用的过滤器表达式的示例。

利用 er_print -filters 命令，过滤器表达式用单引号引起来，如下所示：

er_print -filters 'FNAME("myfunc") SOME IN USTACK' -functions test.1.er

示例 5–1 按名称和堆栈过滤函数

从用户函数堆栈过滤名为 myfunc 的函数：

FNAME("myfunc") SOME IN USTACK

示例 5–2 按线程和 CPU 过滤事件

当线程 1 仅在 CPU 2 上运行时，要查看线程 1 中的事件，请使用：

THRID == 1 && CPUID == 2

示例 5–3 按索引对象过滤事件

如果将索引对象 THRCPU 定义为 "CPUID<<16|THRID "，下面的过滤器与上述当线程 1 仅在 CPU 2 上运行时查看线程 1 中的事件等效：

THRCPU == 0x10002

示例 5–4 过滤指定时间段发生的事件

过滤介于第 5 秒和第 9 秒之间的时间段中发生的实验 2 的事件：

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

示例 5–5 过滤来自特定 Java 类的事件

过滤堆栈中具有特定 Java 类的任何方法的事件（用户视图模式下）：

FNAME("myClass.*") SOME IN USTACK

示例 5–6 按内部函数 ID 和调用序列过滤事件

已知函数 ID（如分析器中所示）时，过滤包含计算机调用堆栈中特定调用序列的事件：

(314,272) ORDERED IN MSTACK

示例 5–7 按状态或持续时间过滤事件

如果 describe 命令列出时钟分析实验的以下属性：

MSTATE    UINT32  Thread state
NTICK     UINT32  Duration

可以使用以下过滤器选择处于特定状态的事件：

MSTATE == 1

或者，可以使用以下过滤器选择处于特定状态且其持续时间比 1 个时钟周期长的事件：

MSTATE == 1 && NTICK > 1

er_print 命令示例

本节提供一些使用 er_print 命令的示例。

示例 5–8 显示函数中时间花费情况的摘要

er_print -functions test.1.er

示例 5–9 显示调用方-被调用方关系

er_print -callers-callees test.1.er

示例 5–10 显示热点源代码行

源代码行信息假设代码已使用 -g 进行编译和链接。将尾随下划线附加到 Fortran 函数和例程的函数名称。函数名称后的 1 用于区分 myfunction 的多个实例。

er_print -source  myfunction 1 test.1.er

示例 5–11 从用户函数堆栈过滤名为 myfunc 的函数：

er_print -filters 'FNAME("myfunc") SOME IN USTACK' -functions test.1.er

示例 5–12 生成类似于 gprof 的输出

以下示例从实验生成一个类似 gprof 的列表。输出是一个名为 er_print.out 的文件，该文件列出前 100 个函数，后跟调用方-被调用方数据（按每个函数的归属用户时间排序）。

er_print -outfile  er_print.out -metrics e.%user -sort e.user \
-limit 100 -func -callers-callees test.1.er

也可以将此示例简化为以下独立的命令。但是请记住，在大型实验或应用程序中对 er_print 的每次调用可能需要花费很长时间。

er_print -metrics  e.%user -limit 100  -functions test.1.er

er_print -metrics  e.%user -callers-callees test.1.er

示例 5–13 仅显示编译器注释

无需运行程序即可使用此命令。

er_src -myfile.o

示例 5–14 使用挂钟分析来列出函数和调用方-被调用方

er_print -metrics  ei.%wall -functions test.1.er

er_print -metrics aei.%wall  -callers-callees test.1.er

示例 5–15 运行包含 er_print 命令的脚本

er_print -script myscriptfile test.1.er

myscriptfile 脚本包含 er_print 命令。脚本文件内容的样例如下：

## myscriptfile

## Send script output to standard output
outfile -

## Display descriptive information about the experiments
header

## Write out the sample data for all experiments
overview

## Write out execution statistics, aggregated over 
## the current sample set for all experiments
statistics

## List functions
functions

## Display status and names of available load objects
object_list


## Write out annotated disassembly code for systime, 
## to file disasm.out
outfile disasm.out
disasm systime


## Write out annotated source code for synprog.c 
## to file source.out
outfile source.out
source synprog.c

## Terminate processing of the script
quit