--- name: "d" section: "7" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/d" --- # d(7) DTrace scripting language overview ## NAME **D** – DTrace scripting language overview ## SYNOPSIS *provider***:** *module***:** *function***:** *name*\[\[ **/** *predicate* **/**\] **{***action***}**\] ## DESCRIPTION **D** is the [dtrace(1)](/dtrace/1.md) scripting language. This manual provides a brief reference of the **D** language and scripting. This manual page serves as a short reference of the language. Refer to books listed in SEE ALSO for a complete reference. ## MACRO VARIABLES | | | | --- | --- | | **Name** | **Description** | | *$1*, *$2*, *$3*, *...* | Macro arguments | | *$egid* | Effective group ID ([getegid(2)](/getegid/2.md)) | | *$euid* | Effective user ID ([geteuid(2)](/geteuid/2.md)) | | *$gid* | Real group ID ([getgid(2)](/getgid/2.md)) | | *$pid* | Process ID ([getpid(2)](/getpid/2.md)) | | *$pgid* | Process group ID ([getpgrp(2)](/getpgrp/2.md)) | | *$ppid* | Parent process ID ([getppid(2)](/getppid/2.md)) | | *$sid* | Session ID ([getsid(2)](/getsid/2.md)) | | *$target* | Target process ID of the process | | *$uid* | Real user ID ([getuid(2)](/getuid/2.md)) | The macro arguments correspond to the command-line operands. They expand to an integer, identifier, or string depending on the context. Prepending a macro argument with an extra dollar sign (‘$’) forces string expansion. For example, ``` dtrace -n 'syscall::fstatat: /execname == $$1/ {}' -- ls ``` uses *$$1* instead of *$1* to expand to a string instead rather than to a global variable identifier. ## PROBE'S DESCRIPTION A probe's description consists of four elements: *provider***:***module***:***function***:***name* The exact meaning of *module*, *function*, and *name* depends on *provider*. ## USER-DEFINED VARIABLE TYPES | | | | --- | --- | | **Type** | **Syntax** | | global | *variable\_name* | | aggregate | **@***variable\_name* | | thread-local | **self-\>***variable\_name* | | clause-local | **this-\>***variable\_name* | *Tips*: - Always use the variable type with the smallest scope to minimize processing overhead. - Use aggregate variables instead of global variables when possible. Aggregate variables are multi-CPU safe in contrast to global variables. ## BUILT-IN VARIABLES ### Probe Arguments - *args\[\]* The array of typed probe arguments. - *arg0*, *...*, *arg9* The untyped probe arguments represented as 64-bit unsigned integers. Only the first ten arguments are available this way. ### Probe Information - *epid* The enabled probe ID which uniquely identifies an enabled probe. An enabled probe is defined by its probe ID, its predicates, and its actions. - *id* The probe ID which uniquely identifies a probe available to DTrace. - *probeprov* The *provider* in the probe's description (*provider***:***module***:***function***:***name*) - *probemod* The *module* in the probe's description (*provider***:***module***:***function***:***name*) - *probefunc* The *function* in the probe's description (*provider***:***module***:***function***:***name*) - *probename* The *name* in the probe's description (*provider***:***module***:***function***:***name*) ### Process Information - *execargs* The process arguments. Effectively, ‘curthread-\>td\_proc-\>p\_args’. - *execname* The name of the current process. Effectively, ‘curthread-\>td\_proc-\>p\_comm’. - *gid* The group ID of the current process. - *pid* The process ID of the current process. - *ppid* The parent process ID of the current process. - *uid* The user ID of the current process. ### Thread Information - *uregs\[\]* The saved user-mode register values. - *cpu* The ID of the current CPU. - *stackdepth* The kernel stack frame depth. - *ustackdepth* The userspace counterpart of *stackdepth*. - *tid* The thread ID. Depending on the context, this can be either the ID of a kernel thread or a thread in a user process. - *errno* The [errno(2)](/errno/2.md) value of the last system call performed by the current thread. - *curlwpsinfo* A pointer to the *lwpsinfo\_t* representation of the current thread. Refer to [dtrace\_proc(4)](/dtrace_proc/4.md) for more details. - *curpsinfo* A pointer to the *psinfo\_t* representation of the current process. Refer to [dtrace\_proc(4)](/dtrace_proc/4.md) for more details. - *curthread* A pointer to the thread struct that is currently on-CPU. E.g., ‘curthread-\>td\_name’ returns the thread name. The ⟨sys/proc.h⟩ header documents all members of *struct* *thread*. - *caller* The address of the kernel thread instruction at the time of execution of the current probe. - *ucaller* The userspace counterpart of *caller*. ### Timestamps - *timestamp* The number of nanoseconds since boot. Suitable for calculating relative time differences of elapsed time and latency. - *vtimestamp* The number of nanoseconds that the current thread spent on CPU. The counter is not increased during handling of a fired DTrace probe. Suitable for calculating relative time differences of on-CPU time. - *walltimestamp* The number of nanoseconds since the Epoch (1970-01-01T00+00:00). Suitable for timestamping logs. ## BUILT-IN FUNCTIONS - *string* **strchr**(*string s*, *char c*) Return a substring of *s* starting at the first occurrence of *c* in *s*. Return NULL if *c* does not occur in *s*. For example, ``` strchr("abc", 'b'); ``` returns ‘bc’ and ``` strchr("abc", 'd'); ``` returns NULL. - *string* **strjoin**(*string s1*, *string s2*) Return a string resulting from concatenating *s1* and *s2*. For example, ``` strjoin("abc", "def") ``` returns ‘abcdef’. - *string* **strrchr**(*string s*, *char c*) Return a substring of *s* starting at the last occurrence of *c* in *s*. Similar to **strchr**(). - *string* **strstr**(*string haystack*, *string needle*) Return a substring of *haystack* starting at the first occurrence of *needle*. Return NULL if *needle* is not a substring of *haystack*. For example, ``` strstr("abc1bc2", "bc") ``` returns ‘bc1bc2’ and ``` strstr("abc", "xy") ``` returns NULL. - *string* **strtok**(*string s*, *string separators*) Tokenize *s* with *separators*. For example, ``` strtok("abcdefg", "xyzd") ``` returns ‘abc’. - *size\_t* **strlen**(*string s*) Return the length of string *s*. - *string* **substr**(*string s*, *int position*, *\[int length\]*) Return a substring of string *s* starting at *position*. The substring will be at most *length*-long. If *length* is not specified, use the rest of the string. If *position* is greater than the size of *s*, return an empty string. For example, ``` substr("abcd", 2) ``` returns ‘cd’, ``` substr("abcd", 2, 1) ``` returns ‘c’, and ``` substr("abcd", 99) ``` returns an empty string. ### Aggregation Functions - **avg**(*value*) Average - **count**() Count - **llquantize**(*value*, *factor*, *low*, *high*, *nsteps*) Log-linear quantization - **lquantize**(*value*, *low*, *high*, *nsteps*) Linear quantization - **max**(*value*) Maximum - **min**(*value*) Minimum - **quantize**(*value*) Power-of-two frequency distribution - **stddev**(*value*) Standard deviation - **sum**(*value*) Sum ### Kernel Destructive Functions By default, [dtrace(1)](/dtrace/1.md) does not permit the use of destructive actions. - **breakpoint**() Set a kernel breakpoint and transfer control to the [ddb(4)](/ddb/4.md) kernel debugger. - **chill**(*nanoseconds*) Spin on the CPU for the specified number of *nanoseconds*. - **panic**() Panic the kernel. ## FILES - */usr/share/dtrace* DTrace scripts shipped with FreeBSD base. ## SEE ALSO [awk(1)](/awk/1.md), [dtrace(1)](/dtrace/1.md), [tracing(7)](/tracing/7.md) *The illumos Dynamic Tracing Guide*, 2008, https://illumos.org/books/dtrace/. Brendan Gregg and Jim Mauro, *DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD*, Prentice Hall, 2011, https://www.brendangregg.com/dtracebook/. George Neville-Neil, Jonathan Anderson, Graeme Jenkinson, Brian Kidney, Domagoj Stolfa, Arun Thomas, and Robert N. M. Watson, *University of Cambridge Computer Laboratory*, OpenDTrace Specification version 1.0, Cambridge, United Kingdom, August 2018, https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf. ## HISTORY This manual page first appeared in FreeBSD 15.0. ## AUTHORS This manual page was written by Mateusz Piotrowski ⟨*0mp@FreeBSD.org*⟩. ## BUGS The *cwd* variable which typically provides the current working directory is not supported on FreeBSD at the moment. Macro variables *$projid* and *$taskid* are always 0 on FreeBSD. Functions **ddi\_pathname**(), **getmajor**(), and **getminor**() are not supported on FreeBSD.