> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/man/man7/d.7.md).

# d.7

`D` — DTrace 脚本语言概述

## 名称

`D`

## 概要

`provider : module : function : name [] [] /predicate /] {action} ]`

## 描述

`D` 是 [dtrace(1)](/man/man1/dtrace.1.md) 脚本语言。本手册提供 `D` 语言和脚本的简要参考。

本手册页作为语言的简短参考。完整参考请参阅 Sx SEE ALSO 中列出的书籍。

## 宏变量

通过 `-p` 标志指定或通过 `-c` 标志创建。

| **名称**               | **描述**              |
| -------------------- | ------------------- |
| `$1 , $2 , $3 , ...` | 宏参数                 |
| `$egid`              | 有效组 ID（getegid(2)）  |
| `$euid`              | 有效用户 ID（geteuid(2)） |
| `$gid`               | 实际组 ID（getgid(2)）   |
| `$pid`               | 进程 ID（getpid(2)）    |
| `$pgid`              | 进程组 ID（getpgrp(2)）  |
| `$ppid`              | 父进程 ID（getppid(2)）  |
| `$sid`               | 会话 ID（getsid(2)）    |
| `$target`            | 进程的目标进程 ID          |
| `$uid`               | 实际用户 ID（getuid(2)）  |

宏参数对应命令行操作数。根据上下文，它们扩展为整数、标识符或字符串。在宏参数前加额外美元符号（`$`）可强制字符串扩展。

例如，

dtrace -n 'syscall::fstatat: /execname == $$1/ {}' -- ls

使用 `$$1` 而非 `$1` 以扩展为字符串而非全局变量标识符。

## 探针描述

探针描述由四个元素组成：

> `provider``:``module` `:` `function` `:` `name`

`module`、`function` 和 `name` 的确切含义取决于 `provider`。

## 用户定义变量类型

| **类型** | **语法**                    |
| ------ | ------------------------- |
| 全局     | `variable_name`           |
| 聚合     | **@**`variable_name`      |
| 线程本地   | **self->**`variable_name` |
| 子句本地   | **this->**`variable_name` |

*提示：*

* 始终使用具有最小作用域的变量类型以最小化处理开销。
* 尽可能使用聚合变量而非全局变量。与全局变量不同，聚合变量是多 CPU 安全的。

## 内置变量

### 探针参数

**`args[]`** 类型化探针参数数组。

**`arg0 , ... , arg9`** 表示为 64 位无符号整数的无类型探针参数。仅前十个参数可通过此方式使用。

### 探针信息

**`epid`** 已启用探针 ID，唯一标识已启用探针。已启用探针由其探针 ID、谓词和操作定义。

**`id`** 探针 ID，唯一标识 DTrace 可用的探针。

**`probeprov`** 探针描述中的 `provider`（`provider` `:` `module` `:` `function` `:` `name`）

**`probemod`** 探针描述中的 `module`（`provider` `:` `module` `:` `function` `:` `name`）

**`probefunc`** 探针描述中的 `function`（`provider` `:` `module` `:` `function` `:` `name`）

**`probename`** 探针描述中的 `name`（`provider` `:` `module` `:` `function` `:` `name`）

### 进程信息

**`execargs`** 进程参数。等效于 `curthread->td_proc->p_args`。

**`execname`** 当前进程的名称。等效于 `curthread->td_proc->p_comm`。

**`gid`** 当前进程的组 ID。

**`pid`** 当前进程的进程 ID。

**`ppid`** 当前进程的父进程 ID。

**`uid`** 当前进程的用户 ID。

### 线程信息

`#include <sys/proc.h>`

**`uregs[]`** 保存的用户模式寄存器值。

**`cpu`** 当前 CPU 的 ID。

**`stackdepth`** 内核栈帧深度。

**`ustackdepth`** `stackdepth` 的用户空间对应物。

**`tid`** 线程 ID。根据上下文，可以是内核线程 ID 或用户进程中的线程 ID。

**`errno`** 当前线程执行的最后一个系统调用的 errno(2) 值。

**`curlwpsinfo`** 指向当前线程的 `lwpsinfo_t` 表示的指针。更多细节参见 [dtrace\_proc(4)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man4/dtrace_proc.4.md)。

**`curpsinfo`** 指向当前进程的 `psinfo_t` 表示的指针。更多细节参见 [dtrace\_proc(4)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man4/dtrace_proc.4.md)。

**`curthread`** 指向当前在 CPU 上的线程结构的指针。例如，`curthread->td_name` 返回线程名称。该头文件记录了 `struct thread` 的所有成员。

**`caller`** 执行当前探针时内核线程指令的地址。

**`ucaller`** `caller` 的用户空间对应物。

### 时间戳

**`timestamp`** 自引导以来的纳秒数。适用于计算相对时间差和延迟。

**`vtimestamp`** 当前线程在 CPU 上花费的纳秒数。处理触发的 DTrace 探针时计数器不增加。适用于计算 CPU 时间的相对时间差。

**`walltimestamp`** 自纪元（1970-01-01T00+00:00）以来的纳秒数。适用于为日志加时间戳。

## 内置函数

strchr("abc", 'b');

strchr("abc", 'd');

strjoin("abc", "def")

strstr("abc1bc2", "bc")

strstr("abc", "xy")

strtok("abcdefg", "xyzd")

substr("abcd", 2)

substr("abcd", 2, 1)

substr("abcd", 99)

**Ft** string Fn strchr string s char c 返回 `s` 中从 `c` 第一次出现处开始的子串。如果 `c` 不在 `s` 中出现则返回 `NULL`。例如，返回 `bc`，返回 `NULL`。

**Ft** string Fn strjoin string s1 string s2 返回连接 `s1` 和 `s2` 的字符串。例如，返回 `abcdef`。

**Ft** string Fn strrchr string s char c 返回 `s` 中从 `c` 最后一次出现处开始的子串。类似 Fn strchr。

**Ft** string Fn strstr string haystack string needle 返回 `haystack` 中从 `needle` 第一次出现处开始的子串。如果 `needle` 不是 `haystack` 的子串则返回 `NULL`。例如，返回 `bc1bc2`，返回 `NULL`。

**Ft** string Fn strtok string s string separators 用 `separators` 标记化 `s`。例如，返回 `abc`。

**Ft** size\_t Fn strlen string s 返回字符串 `s` 的长度。

**Ft** string Fn substr string s int position \[int length] 返回字符串 `s` 从 `position` 开始的子串。子串最多 `length` 长。如果未指定 `length`，使用字符串的其余部分。如果 `position` 大于 `s` 的尺寸，返回空字符串。例如，返回 `cd`，返回 `c`，返回空字符串。

### 聚合函数

**Fn** avg value 平均值 **Fn** count 计数 **Fn** llquantize value factor low high nsteps 对数线性量化 **Fn** lquantize value low high nsteps 线性量化 **Fn** max value 最大值 **Fn** min value 最小值 **Fn** quantize value 二的幂频率分布 **Fn** stddev value 标准差 **Fn** sum value 总和

### 内核破坏性函数

默认情况下，[dtrace(1)](/man/man1/dtrace.1.md) 不允许使用破坏性操作。

**Fn** breakpoint 设置内核断点并将控制权转移到 [ddb(4)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man4/ddb.4.md) 内核调试器。

**Fn** chill nanoseconds 在 CPU 上自旋指定的 `nanoseconds` 纳秒数。

**Fn** panic 使内核崩溃。

## 文件

**`/usr/share/dtrace`** FreeBSD 基本系统附带的 DTrace 脚本。

## 参见

[awk(1)](/man/man1/awk.1.md), [dtrace(1)](/man/man1/dtrace.1.md), [tracing(7)](https://github.com/FreeBSD-Ask/freebsd-man-sc/blob/main/man7/tracing.7.md)

> *The illumos Dynamic Tracing Guide*, 2008.

> Brendan Gregg, Jim Mauro, *DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD*, Prentice Hall, 2011.

> George Neville-Neil, Jonathan Anderson, Graeme Jenkinson, Brian Kidney, Domagoj Stolfa, Arun Thomas, Robert N. M. Watson, "University of Cambridge Computer Laboratory", August 2018.

## 历史

本手册页首次出现于 FreeBSD 15.0。

## 作者

本手册页由 Mateusz Piotrowski <0mp@FreeBSD.org> 编写。

## 缺陷

通常提供当前工作目录的 `cwd` 变量目前在 FreeBSD 上不受支持。

宏变量 `$projid` 和 `$taskid` 在 FreeBSD 上始终为 0。

函数 Fn ddi\_pathname、Fn getmajor 和 Fn getminor 在 FreeBSD 上不受支持。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/man/man7/d.7.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.