test

Solaris 动态跟踪指南

第 14 章 dtrace(1M) 实用程序

dtrace(1M) 命令是 DTrace 工具的通用前端。该命令实现了用于调用 D 语言编译器的简单界面、通过 DTrace 内核工具检索缓存的跟踪数据的功能以及一组用于格式化和列显跟踪数据的基本例程。本章提供 dtrace 命令的完整参考。

说明

dtrace 命令提供了一个可访问 DTrace 工具提供的所有基本服务的通用界面，包括：

还可通过在 #! 声明中使用 dtrace 创建解释程序文件，来创建 D 脚本（请参见第 15 章）。最后，可在不使用 -e 选项启用任何跟踪的情况下，使用 dtrace 尝试编译 D 程序并确定它们的属性，如下文所述。

选项

dtrace 命令接受下列选项：

dtrace [-32 | -64] [-aACeFGHlqSvVwZ] [-bbufsz] [-ccmd] [-Dname [=def]] [-Ipath] [-Lpath] [-ooutput] [-ppid] [-sscript] [-Uname] [-xarg [=val]] [-Xa | c | s | t] [-Pprovider [ [predicate]action]] [-m [ [provider:]module [ [predicate]action]]] [-f [ [provider:]module: ]func [ [predicate]action]] [-n [ [ [provider:]module:]func:]name [ [predicate]action]] [-iprobe-id [ [predicate]action]]

其中，predicate 是置于斜杠 / / 中的任何 D 谓词，而 action 是用括号 { } 括起来的任何 D 语句列表（根据先前说明的 D 语言语法）。如果将 D 程序代码提供为 -P、-m、-f、-n 或 -i 选项的参数，则必须相应地用引号将此文本引起来以避免 shell 对其进行解释。这些选项如下所示：

-32、-64

D 编译器使用操作系统内核的本机数据模型生成程序。可使用 isainfo(1) -b 命令确定当前操作系统的数据模型。如果指定了 -32 选项，dtrace 将强制 D 编译器使用 32 位数据模型编译 D 程序。如果指定了 -64 选项，dtrace 将强制 D 编译器使用 64 位数据模型编译 D 程序。通常这些选项不是必需的，因为 dtrace 会选择本机数据模型作为缺省数据模型。数据模型会影响整数类型的大小和其他语言属性。对任一数据模型编译的 D 程序可在 32 位和64 位内核上执行。-32 和 -64 选项还可确定 -G 选项生成的 ELF 文件格式（ELF32 或 ELF64）。

-a

声明匿名跟踪状态并显示跟踪数据。可将 -a 选项与 -e 选项组合在一起，以强制 dtrace 在使用匿名跟踪状态后立即退出，而不是继续等待新数据。有关匿名跟踪的更多信息，请参见第 36 章。

-A

生成 driver.conf(4) 指令以便进行匿名跟踪。如果指定了 -A 选项，dtrace 将编译使用 -s 选项或在命令行上指定的任何 D 程序，并构造 dtrace(7D) 配置文件指令集，以允许指定探测器进行匿名跟踪（请参见第 36 章），然后退出。缺省情况下，dtrace 尝试将指令存储到文件 /kernel/drv/dtrace.conf 中。可通过使用 -o 选项指定备用输出文件来修改此行为。

-b

设置主体跟踪缓冲区大小。跟踪缓冲区大小可以使用任何大小后缀（k、m、g 或 t），如第 36 章中所述。如果不能分配缓冲区空间，则 dtrace 将根据 bufresize 属性的设置减小缓冲区大小或退出。

-c

运行指定的命令 cmd，并在完成时退出。如果命令行上有多个 -c 选项，dtrace 将在所有命令退出后退出，并报告每个子进程终止时的退出状态。第一个命令的进程 ID 可供在命令行上（或者使用 -s 选项通过 $target 宏变量）指定的任何 D 程序使用。有关宏变量的更多信息，请参阅第 15 章。

-C

在编译 D 程序之前对它们运行 C 预处理程序 cpp(1)。可使用 -D、-U、-I 和 -H 选项将这些选项传递到 C 预处理程序。可使用 -X 选项选择符合 C 标准的程度。有关在调用 C 预处理程序时由 D 编译器定义的标记集的说明，请参阅 -X 选项的说明。

-D

在调用 cpp(1)（使用 -C 选项启用）时定义指定的 name。如果指定了等号 (=) 以及 value，则会将该值赋给名称。此选项将 -D 选项传递到每个 cpp 调用。

-e

在编译所有请求并使用匿名跟踪状态（-a 选项）之后、启用任何探测器之前退出。此选项可与 -a 选项组合在一起，用于列显匿名跟踪数据并退出，它也可以与 D 编译器选项一起使用，用于验证在不实际执行程序并启用相应检测过程的情况下，程序是否会进行编译。

-f

指定要跟踪或列出的函数名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module:function、module:function 或 function。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 function 限定符，则会匹配所有包含相应 function 的探测器。可将可选 D 探测器子句用作 -f 参数的后缀。在命令行上，一次可以指定多个 -f 选项。

-F

通过标识函数的入口和返回位置来合并跟踪输出。对函数入口的探测报告将进行缩进，并在其输出内容前附带 -> 前缀。对函数返回的探测报告将不进行缩进，并在其输出内容前附带 <- 前缀。

-G

生成包含嵌入式 DTrace 程序的 ELF 文件。在程序中指定的 DTrace 探测器将保存在可与其他程序链接的可重定位 ELF 对象中。如果 -o 选项存在，则会使用指定为此操作数参数的路径名来保存 ELF 文件。如果 -o 选项不存在，并且 DTrace 程序包含在名为 filename.s 的文件中，则将使用名称 file .o 来保存 ELF 文件；否则将使用名称 d.out 来保存 ELF 文件。

-H

在调用 cpp(1)（使用 -C 选项启用）时列显所包含文件的路径名。此选项会将 -H 选项传递到每个 cpp 调用，从而使调用将路径名的列表显示到 stderr，每个路径名显示为一行。

-i

指定要跟踪或列出的探测器标识符（-l 选项）。如 dtrace -l 所示，探测器 ID 指定为十进制整数。可将可选 D 探测器子句用作 -i 参数的后缀。在命令行上，一次可以指定多个 -i 选项。

-I

在调用 cpp(1)（使用 -C 选项启用）时，将指定的目录 path 添加到 #include 文件的搜索路径。此选项将 -I 选项传递到每个 cpp 调用。指定的目录将插入到缺省目录列表之前的搜索路径中。

-l

列出探测器而不是启用它们。如果指定了 -l 选项，dtrace 将生成与使用 -P、-m、-f、-n、-i 和 -s 选项指定的说明相匹配的探测器报告。如果未指定其中任何选项，则将列出所有探测器。

-L

将指定的目录 path 添加到 DTrace 库的搜索路径。DTrace 库用于包含可在编写 D 程序时使用的常见定义。指定的 path 将添加到缺省库搜索路径后面。

-m

指定要跟踪或列出的模块名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module 或 module。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 module 限定符，则会匹配所有包含相应 module 的探测器。可将可选 D 探测器子句用作 -m 参数的后缀。在命令行上，一次可以指定多个 -m 选项。

-n

指定要跟踪或列出的探测器名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module:function:name、module:function:name、function:name 或 name。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 name 限定符，则会匹配所有包含相应 name 的探测器。可将可选 D 探测器子句用作 -n 参数的后缀。在命令行上，一次可以指定多个 -n 选项。

-o

对 -A、-G 和 -l 选项或跟踪数据指定 output 文件。如果 -A 选项存在而 -o 不存在，则缺省输出文件为 /kernel/drv/dtrace.conf。如果 -G 选项存在并且 -s 选项的参数为 filename.d 形式，而 -o 不存在，则缺省输出文件为 filename.o；否则，缺省输出文件为 d.out。

-p

获取指定的进程 ID pid，高速缓存其符号表，然后在完成时退出。如果命令行上有多个 -p 选项，dtrace 将在所有命令退出后退出，并报告每个进程终止时的退出状态。第一个进程 ID 可供在命令行上（或使用 -s 选项通过 $target 宏变量）指定的任何 D 程序使用。有关宏变量的更多信息，请参阅第 15 章。

-P

指定要跟踪或列出的提供器名称（-l 选项）。其余的探测器说明字段（模块、函数和名称）将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。可将可选 D 探测器子句用作 -P 参数的后缀。在命令行上，一次可指定多个 -P 选项。

-q

设置静默模式。dtrace 将取消显示消息（如按指定选项和 D 程序相匹配的探测器数目），并且将不列显列标题、CPU ID、探测器 ID，也不会在输出中插入新行。只有 D 程序语句（如 trace() 和 printf()）跟踪并格式化的数据才会显示在 stdout 中。

-s

编译指定的 D 程序源文件。如果 -e 选项存在，则将编译该程序，但不会启用任何检测过程。如果 -l 选项存在，则将编译该程序，并且会列出与其相匹配的一组探测器，但不会启用任何检测过程。如果 -e 和 -l 都不存在，则将启用 D 程序指定的检测过程并开始跟踪。

-S

显示 D 编译器中间代码。对于为每个 D 程序生成的中间代码，D 编译器会将它的报告生成到 stderr。

-U

在调用 cpp(1)（使用 -C 选项启用）时取消定义指定的 name。此选项将 -U 选项传递到每个 cpp 调用。

-v

设置详细模式。如果指定了 -v 选项，dtrace 将生成程序稳定性报告，说明所指定 D 程序的最低接口稳定性和相关性级别。DTrace 稳定性级别将在第 39 章中进一步地详细说明。

-V

报告 dtrace 支持的最高 D 编程接口版本。版本信息将列显到 stdout，然后 dtrace 命令将退出。有关 DTrace 版本控制功能的更多信息，请参见第 41 章。

-w

允许使用 -s、-P、-m、-f、-n 或 -i 选项在指定的 D 程序中执行破坏性操作。如果未指定 -w 选项，dtrace 将不允许编译或启用包含破坏性操作的 D 程序。破坏性操作在第 10 章中进行详细说明。

-x

启用或修改 DTrace 运行时选项或 D 编译器选项。第 16 章中列出了这些选项。将通过指定名称来启用布尔选项。将通过使用等号（=）分隔选项名称和值来设置包含值的选项。

-X

指定符合在调用 cpp(1)（使用 -C 选项启用）时应选择的 ISO C 标准的程度。根据参数字母的值，-X 选项参数会影响 __STDC__ 宏的值和存在性：

a（缺省值）

ISO C 及 K&R 兼容性扩展，包含 ISO C 所需的语义更改。如果未指定 -X，则此模式为缺省模式。在将 cpp 与 -Xa 选项一起调用时，预定义宏 __STDC__ 具有值 0。

c（符合）

严格符合 ISO C（不包含 K&R C 兼容性扩展）。将 cpp 与 -Xc 选项一起调用时，预定义宏 __STDC__ 具有值 1。

s (K&R C)

仅 K&R C。将 cpp 与 -Xs 选项一起调用时，不会定义宏 __STDC__。

t（转换）

ISO C 及 K&R C 兼容性扩展，不包含 ISO C 所需的语义更改。将 cpp 与 -Xt 选项一起调用时，预定义宏 __STDC__ 具有值 0。

因为 -X 选项仅影响 D 编译器调用 C 预处理程序的方式，所以从 D 的角度看来，-Xa 和 -Xt 选项是等价的。提供这两个选项都是为了简化 C 生成环境中设置的重复使用。

无论 -X 模式如何，始终会指定下列附加 C 预处理程序定义，并且它们在所有模式中有效：

  • __sun

  • __unix

  • __SVR4

  • __sparc（仅在 SPARC® 系统上）

  • __sparcv9（仅当在 SPARC® 系统上编译 64 位程序时）

  • __i386（仅当在 x86 系统上编译 32 位程序时）

  • __amd64（仅当在 x86 系统上编译 64 位程序时）

  • __'uname -s' _'uname -r'，将 uname 输出中的小数点替换为下划线 (_)，如 __SunOS_5_10

  • __SUNW_D=1

  • __SUNW_D_VERSION=0xMMmmmuuu（其中，MM 是十六进制的主发行版本号，mmm 是十六进制的次发行版本号，而 uuu 是十六进制的微发行版本号；有关 DTrace 版本控制的更多信息，请参见第 41 章）

-Z

允许与任何探测器都不匹配的探测器说明。在未指定 -Z 选项时，如果在 D 程序文件中（使用 -s 选项）或在命令行上（使用 -P、-m、-f、-n 或 -i 选项）指定的任何探测器说明中包含不与任何已知探测器匹配的说明，dtrace 会报告错误并退出。

操作数

可在 dtrace 命令行上指定零个或多个其他参数，来定义一组宏变量（$1、$2 等），以在使用 -s 选项指定的或在命令行上指定的任何 D 程序中使用。宏变量的用法将在第 15 章进一步地说明。

退出状态

dtrace 实用程序将返回下列退出值：

0

成功完成了指定的请求。对于 D 程序请求，退出状态 0 指示已成功编译程序，并且已成功启用探测器，或者已成功检索匿名状态。即使指定的跟踪请求遇到错误或删除，dtrace 也会返回 0。

1

发生了致命错误。对于 D 程序请求，退出状态 1 指示程序编译失败或者无法满足指定的请求。

2

指定的命令行选项或参数无效。