NAME

D — DTrace scripting language overview

SYNOPSIS

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

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.

A probe's description consists of four elements:

provider:module:function:name

The exact meaning of module, function, and name depends on provider.

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.

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.

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).

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.

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.

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.

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

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.

This manual page first appeared in FreeBSD 15.0.

This manual page was written by Mateusz Piotrowski <0mp@FreeBSD.org>.

The cwd variable which typically provides the current working directory is not supported on FreeBSD at the moment.