1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> 5.\" 6.Dd June 14, 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.Cm / 22.Ar predicate 23.Cm / 24.Sm on 25.Oc 26.Op Cm \&{ Ns Ar action Ns Cm \&} 27.Sh DESCRIPTION 28.Nm D 29is the 30.Xr dtrace 1 31scripting language. 32This manual provides a brief reference of the 33.Nm 34language and scripting. 35.Pp 36This manual page serves as a short reference of the language. 37Refer to books listed in 38.Sx SEE ALSO 39for a complete reference. 40.Sh PROBE'S DESCRIPTION 41A probe's description consists of four elements: 42.Sm off 43.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name 44.Sm on 45.Pp 46The exact meaning of 47.Ar module , 48.Ar function , 49and 50.Ar name 51depends on 52.Ar provider . 53.Sh USER-DEFINED VARIABLE TYPES 54.Bl -column "thread-local" "Syntax" 55.It Sy Type Ta Sy Syntax 56.It global Ta Va variable_name 57.It thread-local Ta Sy self-> Ns Va variable_name 58.It clause-local Ta Sy this-> Ns Va variable_name 59.It aggregate Ta Sy @ Ns Va variable_name 60.El 61.Pp 62.Em Tips : 63.Bl -dash -compact 64.It 65Always use the variable type with the smallest scope 66to minimize processing overhead. 67.It 68Use aggregate variables instead of global variables when possible. 69Aggregate variables are multi-CPU safe in contrast to global variables. 70.El 71.Sh BUILT-IN VARIABLES 72.Ss Probe Arguments 73.Bl -tag -width "arg0, ..., arg9" 74.It Va args[] 75The array of typed probe arguments. 76.It Va arg0 , ... , arg9 77The untyped probe arguments represented as 64-bit unsigned integers. 78Only the first ten arguments are available this way. 79.El 80.Ss Probe Information 81.Bl -tag -width probeprov 82.It Va epid 83The enabled probe ID which uniquely identifies an enabled probe. 84An enabled probe is defined by its probe ID, its predicates, and its actions. 85.It Va id 86The probe ID which uniquely identifies a probe available to DTrace. 87.It Va probeprov 88The 89.Ar provider 90in the probe's description 91.Sm off 92.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 93.Sm on . 94.It Va probemod 95The 96.Ar module 97in the probe's description 98.Sm off 99.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 100.Sm on . 101.It Va probefunc 102The 103.Ar function 104in the probe's description 105.Sm off 106.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 107.Sm on . 108.It Va probename 109The 110.Ar name 111in the probe's description 112.Sm off 113.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name 114.Sm on . 115.El 116.Ss Process Information 117.Bl -tag -width execname 118.It Va execargs 119The process arguments. 120Effectively, 121.Ql curthread->td_proc->p_args . 122.It Va execname 123The name of the current process. 124Effectively, 125.Ql curthread->td_proc->p_comm . 126.It Va gid 127The group ID of the current process. 128.It Va pid 129The process ID of the current process. 130.It Va ppid 131The parent process ID of the current process. 132.It Va uid 133The user ID of the current process. 134.El 135.Ss Thread Information 136.Bl -tag -width curlwpsinfo 137.It Va uregs[] 138The saved user-mode register values. 139.It Va cpu 140The ID of the current CPU. 141.It Va stackdepth 142The kernel stack frame depth. 143.It Va ustackdepth 144The userspace counterpart of 145.Va stackdepth . 146.It Va tid 147The thread ID. 148Depending on the context, 149this can be either the ID of a kernel thread or a thread in a user process. 150.It Va errno 151The 152.Xr errno 2 153value of the last system call performed by the current thread. 154.It Va curlwpsinfo 155A pointer to the 156.Vt lwpsinfo_t 157representation of the current thread. 158Refer to 159.Xr dtrace_proc 4 160for more details. 161.It Va curpsinfo 162A pointer to the 163.Vt psinfo_t 164representation of the current process. 165Refer to 166.Xr dtrace_proc 4 167for more details. 168.It Va curthread 169A pointer to the thread struct that is currently on-CPU. 170E.g., 171.Ql curthread->td_name 172returns the thread name. 173The 174.In sys/proc.h 175header documents all members of 176.Vt struct thread . 177.It Va caller 178The address of the kernel thread instruction at the time of execution 179of the current probe. 180.It Va ucaller 181The userspace counterpart of 182.Va caller . 183.El 184.Ss Timestamps 185.Bl -tag -width walltimestamp 186.It Va timestamp 187The number of nanoseconds since boot. 188Suitable for calculating relative time differences of elapsed time and latency. 189.It Va vtimestamp 190The number of nanoseconds that the current thread spent on CPU. 191The counter is not increased during handling of a fired DTrace probe. 192Suitable for calculating relative time differences of on-CPU time. 193.It Va walltimestamp 194The number of nanoseconds since the Epoch 195.Pq 1970-01-01T00+00:00 . 196Suitable for timestamping logs. 197.El 198.Sh BUILT-IN FUNCTIONS 199.Ss Aggregation Functions 200.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" 201.It Fn avg value 202Average 203.It Fn count 204Count 205.It Fn llquantize value factor low high nsteps 206Log-linear quantization 207.It Fn lquantize value low high nsteps 208Linear quantization 209.It Fn max value 210Maximum 211.It Fn min value 212Minimum 213.It Fn quantize value 214Power-of-two frequency distribution 215.It Fn stddev value 216Standard deviation 217.It Fn sum value 218Sum 219.El 220.Ss Kernel Destructive Functions 221By default, 222.Xr dtrace 1 223does not permit the use of destructive actions. 224.Bl -tag -width "chill(nanoseconds)" 225.It Fn breakpoint 226Set a kernel breakpoint and transfer control to 227the 228.Xr ddb 4 229kernel debugger. 230.It Fn chill nanoseconds 231Spin on the CPU for the specified number of 232.Fa nanoseconds . 233.It Fn panic 234Panic the kernel. 235.El 236.Sh FILES 237.Bl -tag -width /usr/share/dtrace 238.It Pa /usr/share/dtrace 239DTrace scripts shipped with 240.Fx 241base. 242.El 243.Sh SEE ALSO 244.Xr awk 1 , 245.Xr dtrace 1 , 246.Xr tracing 7 247.Rs 248.%B The illumos Dynamic Tracing Guide 249.%D 2008 250.%U https://illumos.org/books/dtrace/ 251.Re 252.Rs 253.%A Brendan Gregg 254.%A Jim Mauro 255.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD 256.%I Prentice Hall 257.%D 2011 258.%U https://www.brendangregg.com/dtracebook/ 259.Re 260.Rs 261.%A George Neville-Neil 262.%A Jonathan Anderson 263.%A Graeme Jenkinson 264.%A Brian Kidney 265.%A Domagoj Stolfa 266.%A Arun Thomas 267.%A Robert N. M. Watson 268.%C Cambridge, United Kingdom 269.%D August 2018 270.%T Univeristy of Cambridge Computer Laboratory 271.%R OpenDTrace Specification version 1.0 272.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf 273.Re 274.Sh HISTORY 275This manual page first appeared in 276.Fx 15.0 . 277.Sh AUTHORS 278.An -nosplit 279This manual page was written by 280.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 281.Sh BUGS 282The 283.Va cwd 284variable which typically provides the current working directory is 285not supported on 286.Fx 287at the moment. 288