1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd September 24, 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 thread-local Ta Sy self-> Ns Va variable_name 60.It clause-local Ta Sy this-> Ns Va variable_name 61.It aggregate Ta Sy @ 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.Ss Aggregation Functions 202.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" 203.It Fn avg value 204Average 205.It Fn count 206Count 207.It Fn llquantize value factor low high nsteps 208Log-linear quantization 209.It Fn lquantize value low high nsteps 210Linear quantization 211.It Fn max value 212Maximum 213.It Fn min value 214Minimum 215.It Fn quantize value 216Power-of-two frequency distribution 217.It Fn stddev value 218Standard deviation 219.It Fn sum value 220Sum 221.El 222.Ss Kernel Destructive Functions 223By default, 224.Xr dtrace 1 225does not permit the use of destructive actions. 226.Bl -tag -width "chill(nanoseconds)" 227.It Fn breakpoint 228Set a kernel breakpoint and transfer control to 229the 230.Xr ddb 4 231kernel debugger. 232.It Fn chill nanoseconds 233Spin on the CPU for the specified number of 234.Fa nanoseconds . 235.It Fn panic 236Panic the kernel. 237.El 238.Sh FILES 239.Bl -tag -width /usr/share/dtrace 240.It Pa /usr/share/dtrace 241DTrace scripts shipped with 242.Fx 243base. 244.El 245.Sh SEE ALSO 246.Xr awk 1 , 247.Xr dtrace 1 , 248.Xr tracing 7 249.Rs 250.%B The illumos Dynamic Tracing Guide 251.%D 2008 252.%U https://illumos.org/books/dtrace/ 253.Re 254.Rs 255.%A Brendan Gregg 256.%A Jim Mauro 257.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 258.%I Prentice Hall 259.%D 2011 260.%U https://www.brendangregg.com/dtracebook/ 261.Re 262.Rs 263.%A George Neville-Neil 264.%A Jonathan Anderson 265.%A Graeme Jenkinson 266.%A Brian Kidney 267.%A Domagoj Stolfa 268.%A Arun Thomas 269.%A Robert N. M. Watson 270.%C Cambridge, United Kingdom 271.%D August 2018 272.%T Univeristy of Cambridge Computer Laboratory 273.%R OpenDTrace Specification version 1.0 274.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf 275.Re 276.Sh HISTORY 277This manual page first appeared in 278.Fx 15.0 . 279.Sh AUTHORS 280.An -nosplit 281This manual page was written by 282.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 283.Sh BUGS 284The 285.Va cwd 286variable which typically provides the current working directory is 287not supported on 288.Fx 289at the moment. 290