1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd October 28, 2025 7.Dt D 7 8.Os 9.Sh NAME 10.Nm D 11.Nd DTrace scripting language overview 12.Sh SYNOPSIS 13.Sm off 14.Ar provider Cm \&: 15.Ar module Cm \&: 16.Ar function Cm \&: 17.Ar name 18.Sm on 19.Sm off 20.Oo 21.Oo 22.Cm / 23.Ar predicate 24.Cm / 25.Sm on 26.Oc 27.Cm \&{ Ns Ar action Ns Cm \&} 28.Oc 29.Sh DESCRIPTION 30.Nm D 31is the 32.Xr dtrace 1 33scripting language. 34This manual provides a brief reference of the 35.Nm 36language and scripting. 37.Pp 38This manual page serves as a short reference of the language. 39Refer to books listed in 40.Sx SEE ALSO 41for a complete reference. 42.Sh PROBE'S DESCRIPTION 43A probe's description consists of four elements: 44.Sm off 45.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name 46.Sm on 47.Pp 48The exact meaning of 49.Ar module , 50.Ar function , 51and 52.Ar name 53depends on 54.Ar provider . 55.Sh USER-DEFINED VARIABLE TYPES 56.Bl -column "thread-local" "Syntax" 57.It Sy Type Ta Sy Syntax 58.It global Ta Va variable_name 59.It aggregate Ta Sy @ Ns Va variable_name 60.It thread-local Ta Sy self-> Ns Va variable_name 61.It clause-local Ta Sy this-> Ns Va variable_name 62.El 63.Pp 64.Em Tips : 65.Bl -dash -compact 66.It 67Always use the variable type with the smallest scope 68to minimize processing overhead. 69.It 70Use aggregate variables instead of global variables when possible. 71Aggregate variables are multi-CPU safe in contrast to global variables. 72.El 73.Sh BUILT-IN VARIABLES 74.Ss Probe Arguments 75.Bl -tag -width "arg0, ..., arg9" 76.It Va args[] 77The array of typed probe arguments. 78.It Va arg0 , ... , arg9 79The untyped probe arguments represented as 64-bit unsigned integers. 80Only the first ten arguments are available this way. 81.El 82.Ss Probe Information 83.Bl -tag -width probeprov 84.It Va epid 85The enabled probe ID which uniquely identifies an enabled probe. 86An enabled probe is defined by its probe ID, its predicates, and its actions. 87.It Va id 88The probe ID which uniquely identifies a probe available to DTrace. 89.It Va probeprov 90The 91.Ar provider 92in the probe's description 93.Sm off 94.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 95.Sm on . 96.It Va probemod 97The 98.Ar module 99in the probe's description 100.Sm off 101.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 102.Sm on . 103.It Va probefunc 104The 105.Ar function 106in the probe's description 107.Sm off 108.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 109.Sm on . 110.It Va probename 111The 112.Ar name 113in the probe's description 114.Sm off 115.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 116.Sm on . 117.El 118.Ss Process Information 119.Bl -tag -width execname 120.It Va execargs 121The process arguments. 122Effectively, 123.Ql curthread->td_proc->p_args . 124.It Va execname 125The name of the current process. 126Effectively, 127.Ql curthread->td_proc->p_comm . 128.It Va gid 129The group ID of the current process. 130.It Va pid 131The process ID of the current process. 132.It Va ppid 133The parent process ID of the current process. 134.It Va uid 135The user ID of the current process. 136.El 137.Ss Thread Information 138.Bl -tag -width curlwpsinfo 139.It Va uregs[] 140The saved user-mode register values. 141.It Va cpu 142The ID of the current CPU. 143.It Va stackdepth 144The kernel stack frame depth. 145.It Va ustackdepth 146The userspace counterpart of 147.Va stackdepth . 148.It Va tid 149The thread ID. 150Depending on the context, 151this can be either the ID of a kernel thread or a thread in a user process. 152.It Va errno 153The 154.Xr errno 2 155value of the last system call performed by the current thread. 156.It Va curlwpsinfo 157A pointer to the 158.Vt lwpsinfo_t 159representation of the current thread. 160Refer to 161.Xr dtrace_proc 4 162for more details. 163.It Va curpsinfo 164A pointer to the 165.Vt psinfo_t 166representation of the current process. 167Refer to 168.Xr dtrace_proc 4 169for more details. 170.It Va curthread 171A pointer to the thread struct that is currently on-CPU. 172E.g., 173.Ql curthread->td_name 174returns the thread name. 175The 176.In sys/proc.h 177header documents all members of 178.Vt struct thread . 179.It Va caller 180The address of the kernel thread instruction at the time of execution 181of the current probe. 182.It Va ucaller 183The userspace counterpart of 184.Va caller . 185.El 186.Ss Timestamps 187.Bl -tag -width walltimestamp 188.It Va timestamp 189The number of nanoseconds since boot. 190Suitable for calculating relative time differences of elapsed time and latency. 191.It Va vtimestamp 192The number of nanoseconds that the current thread spent on CPU. 193The counter is not increased during handling of a fired DTrace probe. 194Suitable for calculating relative time differences of on-CPU time. 195.It Va walltimestamp 196The number of nanoseconds since the Epoch 197.Pq 1970-01-01T00+00:00 . 198Suitable for timestamping logs. 199.El 200.Sh BUILT-IN FUNCTIONS 201.\" Keep the indentation wide enough for the reader to be able to skim through 202.\" function names quickly. 203.Bl -tag -width "size_t strlen" 204.It Ft string Fn strchr "string s" "char c" 205Return a substring of 206.Fa s 207starting at the first occurance of 208.Fa c 209in 210.Fa s . 211Return 212.Dv NULL 213if 214.Fa c 215does not occur in 216.Fa s . 217.Pp 218For example, 219.Bd -literal -compact -offset indent 220strchr("abc", 'b'); 221.Ed 222returns 223.Ql "bc" 224and 225.Bd -literal -compact -offset indent 226strchr("abc", 'd'); 227.Ed 228returns 229.Dv NULL . 230.It Ft string Fn strjoin "string s1" "string s2" 231Return a string resulting from concatenating 232.Fa s1 233and 234.Fa s2 . 235.Pp 236For example, 237.Bd -literal -compact -offset indent 238strjoin("abc", "def") 239.Ed 240returns 241.Ql abcdef . 242.It Ft string Fn strrchr "string s" "char c" 243Return a substring of 244.Fa s 245starting at the last occurance of 246.Fa c 247in 248.Fa s . 249Similar to 250.Fn strchr . 251.It Ft string Fn strstr "string haystack" "string needle" 252Return a substring of 253.Fa haystack 254starting at the first occurrence of 255.Fa needle . 256Return 257.Dv NULL 258if 259.Fa needle 260is not a substring of 261.Fa haystack . 262.Pp 263For example, 264.Bd -literal -compact -offset indent 265strstr("abc1bc2", "bc") 266.Ed 267returns 268.Ql bc1bc2 269and 270.Bd -literal -compact -offset indent 271strstr("abc", "xy") 272.Ed 273returns 274.Dv NULL . 275.It Ft string Fn strtok "string s" "string separators" 276Tokenize 277.Fa s 278with 279.Fa separators . 280.Pp 281For example, 282.Bd -literal -compact -offset indent 283strtok("abcdefg", "xyzd") 284.Ed 285returns 286.Ql abc . 287.It Ft size_t Fn strlen "string s" 288Return the length of string 289.Fa s . 290.It Ft string Fn substr "string s" "int position" "[int length]" 291Return a 292substring of string 293.Fa s 294starting at 295.Fa position . 296The substring will be at most 297.Fa length Ns -long . 298If 299.Fa length 300is not specified, use the rest of the string. 301If 302.Fa position 303is greater than 304the size of 305.Fa s , 306return an empty string. 307.Pp 308For example, 309.Bd -literal -compact -offset indent 310substr("abcd", 2) 311.Ed 312returns 313.Ql cd , 314.Bd -literal -compact -offset indent 315substr("abcd", 2, 1) 316.Ed 317returns 318.Ql c , 319and 320.Bd -literal -compact -offset indent 321substr("abcd", 99) 322.Ed 323returns an empty string. 324.El 325.Ss Aggregation Functions 326.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" 327.It Fn avg value 328Average 329.It Fn count 330Count 331.It Fn llquantize value factor low high nsteps 332Log-linear quantization 333.It Fn lquantize value low high nsteps 334Linear quantization 335.It Fn max value 336Maximum 337.It Fn min value 338Minimum 339.It Fn quantize value 340Power-of-two frequency distribution 341.It Fn stddev value 342Standard deviation 343.It Fn sum value 344Sum 345.El 346.Ss Kernel Destructive Functions 347By default, 348.Xr dtrace 1 349does not permit the use of destructive actions. 350.Bl -tag -width "chill(nanoseconds)" 351.It Fn breakpoint 352Set a kernel breakpoint and transfer control to 353the 354.Xr ddb 4 355kernel debugger. 356.It Fn chill nanoseconds 357Spin on the CPU for the specified number of 358.Fa nanoseconds . 359.It Fn panic 360Panic the kernel. 361.El 362.Sh FILES 363.Bl -tag -width /usr/share/dtrace 364.It Pa /usr/share/dtrace 365DTrace scripts shipped with 366.Fx 367base. 368.El 369.Sh SEE ALSO 370.Xr awk 1 , 371.Xr dtrace 1 , 372.Xr tracing 7 373.Rs 374.%B The illumos Dynamic Tracing Guide 375.%D 2008 376.%U https://illumos.org/books/dtrace/ 377.Re 378.Rs 379.%A Brendan Gregg 380.%A Jim Mauro 381.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 382.%I Prentice Hall 383.%D 2011 384.%U https://www.brendangregg.com/dtracebook/ 385.Re 386.Rs 387.%A George Neville-Neil 388.%A Jonathan Anderson 389.%A Graeme Jenkinson 390.%A Brian Kidney 391.%A Domagoj Stolfa 392.%A Arun Thomas 393.%A Robert N. M. Watson 394.%C Cambridge, United Kingdom 395.%D August 2018 396.%T Univeristy of Cambridge Computer Laboratory 397.%R OpenDTrace Specification version 1.0 398.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf 399.Re 400.Sh HISTORY 401This manual page first appeared in 402.Fx 15.0 . 403.Sh AUTHORS 404.An -nosplit 405This manual page was written by 406.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 407.Sh BUGS 408The 409.Va cwd 410variable which typically provides the current working directory is 411not supported on 412.Fx 413at the moment. 414