.\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2025 Mateusz Piotrowski <[email protected]> .\" .Dd October 28, 2025 .Dt D 7 .Os .Sh NAME .Nm D .Nd DTrace scripting language overview .Sh SYNOPSIS .Sm off .Ar provider Cm \&: .Ar module Cm \&: .Ar function Cm \&: .Ar name .Sm on .Sm off .Oo .Oo .Cm / .Ar predicate .Cm / .Sm on .Oc .Cm \&{ Ns Ar action Ns Cm \&} .Oc .Sh DESCRIPTION .Nm D is the .Xr dtrace 1 scripting language. This manual provides a brief reference of the .Nm language and scripting. .Pp This manual page serves as a short reference of the language. Refer to books listed in .Sx SEE ALSO for a complete reference. .Sh PROBE'S DESCRIPTION A probe's description consists of four elements: .Sm off .D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name .Sm on .Pp The exact meaning of .Ar module , .Ar function , and .Ar name depends on .Ar provider . .Sh USER-DEFINED VARIABLE TYPES .Bl -column "thread-local" "Syntax" .It Sy Type Ta Sy Syntax .It global Ta Va variable_name .It aggregate Ta Sy @ Ns Va variable_name .It thread-local Ta Sy self-> Ns Va variable_name .It clause-local Ta Sy this-> Ns Va variable_name .El .Pp .Em Tips : .Bl -dash -compact .It Always use the variable type with the smallest scope to minimize processing overhead. .It Use aggregate variables instead of global variables when possible. Aggregate variables are multi-CPU safe in contrast to global variables. .El .Sh BUILT-IN VARIABLES .Ss Probe Arguments .Bl -tag -width "arg0, ..., arg9" .It Va args[] The array of typed probe arguments. .It Va arg0 , ... , arg9 The untyped probe arguments represented as 64-bit unsigned integers. Only the first ten arguments are available this way. .El .Ss Probe Information .Bl -tag -width probeprov .It Va 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. .It Va id The probe ID which uniquely identifies a probe available to DTrace. .It Va probeprov The .Ar provider in the probe's description .Sm off .Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name .Sm on . .It Va probemod The .Ar module in the probe's description .Sm off .Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name .Sm on . .It Va probefunc The .Ar function in the probe's description .Sm off .Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name .Sm on . .It Va probename The .Ar name in the probe's description .Sm off .Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name .Sm on . .El .Ss Process Information .Bl -tag -width execname .It Va execargs The process arguments. Effectively, .Ql curthread->td_proc->p_args . .It Va execname The name of the current process. Effectively, .Ql curthread->td_proc->p_comm . .It Va gid The group ID of the current process. .It Va pid The process ID of the current process. .It Va ppid The parent process ID of the current process. .It Va uid The user ID of the current process. .El .Ss Thread Information .Bl -tag -width curlwpsinfo .It Va uregs[] The saved user-mode register values. .It Va cpu The ID of the current CPU. .It Va stackdepth The kernel stack frame depth. .It Va ustackdepth The userspace counterpart of .Va stackdepth . .It Va 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. .It Va errno The .Xr errno 2 value of the last system call performed by the current thread. .It Va curlwpsinfo A pointer to the .Vt lwpsinfo_t representation of the current thread. Refer to .Xr dtrace_proc 4 for more details. .It Va curpsinfo A pointer to the .Vt psinfo_t representation of the current process. Refer to .Xr dtrace_proc 4 for more details. .It Va curthread A pointer to the thread struct that is currently on-CPU. E.g., .Ql curthread->td_name returns the thread name. The .In sys/proc.h header documents all members of .Vt struct thread . .It Va caller The address of the kernel thread instruction at the time of execution of the current probe. .It Va ucaller The userspace counterpart of .Va caller . .El .Ss Timestamps .Bl -tag -width walltimestamp .It Va timestamp The number of nanoseconds since boot. Suitable for calculating relative time differences of elapsed time and latency. .It Va 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. .It Va walltimestamp The number of nanoseconds since the Epoch .Pq 1970-01-01T00+00:00 . Suitable for timestamping logs. .El .Sh BUILT-IN FUNCTIONS .\" Keep the indentation wide enough for the reader to be able to skim through .\" function names quickly. .Bl -tag -width "size_t strlen" .It Ft string Fn strchr "string s" "char c" Return a substring of .Fa s starting at the first occurance of .Fa c in .Fa s . Return .Dv NULL if .Fa c does not occur in .Fa s . .Pp For example, .Bd -literal -compact -offset indent strchr("abc", 'b'); .Ed returns .Ql "bc" and .Bd -literal -compact -offset indent strchr("abc", 'd'); .Ed returns .Dv NULL . .It Ft string Fn strjoin "string s1" "string s2" Return a string resulting from concatenating .Fa s1 and .Fa s2 . .Pp For example, .Bd -literal -compact -offset indent strjoin("abc", "def") .Ed returns .Ql abcdef . .It Ft string Fn strrchr "string s" "char c" Return a substring of .Fa s starting at the last occurance of .Fa c in .Fa s . Similar to .Fn strchr . .It Ft string Fn strstr "string haystack" "string needle" Return a substring of .Fa haystack starting at the first occurrence of .Fa needle . Return .Dv NULL if .Fa needle is not a substring of .Fa haystack . .Pp For example, .Bd -literal -compact -offset indent strstr("abc1bc2", "bc") .Ed returns .Ql bc1bc2 and .Bd -literal -compact -offset indent strstr("abc", "xy") .Ed returns .Dv NULL . .It Ft string Fn strtok "string s" "string separators" Tokenize .Fa s with .Fa separators . .Pp For example, .Bd -literal -compact -offset indent strtok("abcdefg", "xyzd") .Ed returns .Ql abc . .It Ft size_t Fn strlen "string s" Return the length of string .Fa s . .It Ft string Fn substr "string s" "int position" "[int length]" Return a substring of string .Fa s starting at .Fa position . The substring will be at most .Fa length Ns -long . If .Fa length is not specified, use the rest of the string. If .Fa position is greater than the size of .Fa s , return an empty string. .Pp For example, .Bd -literal -compact -offset indent substr("abcd", 2) .Ed returns .Ql cd , .Bd -literal -compact -offset indent substr("abcd", 2, 1) .Ed returns .Ql c , and .Bd -literal -compact -offset indent substr("abcd", 99) .Ed returns an empty string. .El .Ss Aggregation Functions .Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" .It Fn avg value Average .It Fn count Count .It Fn llquantize value factor low high nsteps Log-linear quantization .It Fn lquantize value low high nsteps Linear quantization .It Fn max value Maximum .It Fn min value Minimum .It Fn quantize value Power-of-two frequency distribution .It Fn stddev value Standard deviation .It Fn sum value Sum .El .Ss Kernel Destructive Functions By default, .Xr dtrace 1 does not permit the use of destructive actions. .Bl -tag -width "chill(nanoseconds)" .It Fn breakpoint Set a kernel breakpoint and transfer control to the .Xr ddb 4 kernel debugger. .It Fn chill nanoseconds Spin on the CPU for the specified number of .Fa nanoseconds . .It Fn panic Panic the kernel. .El .Sh FILES .Bl -tag -width /usr/share/dtrace .It Pa /usr/share/dtrace DTrace scripts shipped with .Fx base. .El .Sh SEE ALSO .Xr awk 1 , .Xr dtrace 1 , .Xr tracing 7 .Rs .%B The illumos Dynamic Tracing Guide .%D 2008 .%U https://illumos.org/books/dtrace/ .Re .Rs .%A Brendan Gregg .%A Jim Mauro .%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD .%I Prentice Hall .%D 2011 .%U https://www.brendangregg.com/dtracebook/ .Re .Rs .%A George Neville-Neil .%A Jonathan Anderson .%A Graeme Jenkinson .%A Brian Kidney .%A Domagoj Stolfa .%A Arun Thomas .%A Robert N. M. Watson .%C Cambridge, United Kingdom .%D August 2018 .%T Univeristy of Cambridge Computer Laboratory .%R OpenDTrace Specification version 1.0 .%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf .Re .Sh HISTORY This manual page first appeared in .Fx 15.0 . .Sh AUTHORS .An -nosplit This manual page was written by .An Mateusz Piotrowski Aq Mt [email protected] . .Sh BUGS The .Va cwd variable which typically provides the current working directory is not supported on .Fx at the moment.
