D(7) FreeBSD Miscellaneous Information Manual D(7)
NAME
D - DTrace scripting language overview
SYNOPSIS
provider:module:function:name [[/predicate/] {action}]
DESCRIPTION
D is the dtrace(1) 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))
$euid Effective user ID (geteuid(2))
$gid Real group ID (getgid(2))
$pid Process ID (getpid(2))
$pgid Process group ID (getpgrp(2))
$ppid Parent process ID (getppid(2))
$sid Session ID (getsid(2))
$target Target process ID of the process specified via the -p
flag or created via the -c flag.
$uid Real user ID (getuid(2))
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) 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) for more details.
curpsinfo A pointer to the psinfo_t representation of the current
process. Refer to dtrace_proc(4) 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) does not permit the use of destructive actions.
breakpoint() Set a kernel breakpoint and transfer control to the
ddb(4) 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), dtrace(1), tracing(7)
The illumos Dynamic Tracing Guide, https://illumos.org/books/dtrace/,
2008.
Brendan Gregg and Jim Mauro, DTrace: Dynamic Tracing in Oracle Solaris,
Mac OS X and FreeBSD, Prentice Hall,
https://www.brendangregg.com/dtracebook/, 2011.
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,
https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf, Cambridge,
United Kingdom, August 2018.
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.
FreeBSD 15.1-STABLE-HBSD May 7, 2026 D(7)