1.\" $OpenBSD: bt.5,v 1.17 2023/10/22 19:30:35 cheloha Exp $ 2.\" 3.\" Copyright (c) 2019 Martin Pieuchot <mpi@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 22 2023 $ 18.Dt BT 5 19.Os 20.Sh NAME 21.Nm BT 22.Nd Bug Tracing language 23.Sh SYNTAX 24.D1 Ar probe Ic \&/ Ar filter Ic \&/ \&{ Ar action Ic \&} 25.Sh DESCRIPTION 26The 27.Nm 28language, also known as BPFtrace syntax, describes how to format and display 29information gathered from specified 30.Ar probe 31events. 32.Pp 33Events are generated by the dynamic tracer 34.Xr dt 4 35when an enabled 36.Ar probe 37is triggered. 38They are periodically collected by 39.Xr btrace 8 , 40which formats them using the corresponding 41.Ar action . 42If a recorded event doesn't match the optional 43.Ar filter , 44it will be silently ignored. 45.Pp 46A valid 47.Nm 48source file contains at least one 49.Ar probe 50clause associated with an 51.Ar action 52statement. 53.Sh PROBE 54The list of available probes may vary from system to system and can be queried 55with 56.Xr btrace 8 . 57.Pp 58The special probes 59.Ic BEGIN 60and 61.Ic END 62may be used to manipulate states before the first event is recorded and after 63the last. 64They cannot be combined with any 65.Ar filter . 66.Sh FILTER 67Define under which condition an event should be recorded when its related 68.Ar probe 69is executed. 70An empty 71.Ar filter 72means record all events. 73.Pp 74Variable names available in filters: 75.Pp 76.Bl -tag -width "kstack " -compact -offset indent 77.It Va pid 78Process ID of the current thread. 79.It Va tid 80Thread ID of the current thread. 81.El 82.Sh ACTION 83An action is a sequence of statements that are evaluated for each event recorded 84by the associated 85.Ar probe . 86.Pp 87Variable names with special meaning: 88.Pp 89.Bl -tag -width "kstack " -compact -offset indent 90.It Va $N 91Command line argument 92.Va N 93after the script name. 94.It Va argN 95Argument 96.Va N 97of the corresponding probe. 98.It Va comm 99Command name of the current process. 100.It Va cpu 101ID of the processor that recorded the event. 102.It Va kstack 103Kernel stack of the current thread. 104.It Va nsecs 105Timestamp of the event in nanoseconds. 106.It Va pid 107Process ID of the current thread. 108.It Va probe 109Full name of the probe. 110.It Va retval 111Return value of the traced syscall. 112.It Va tid 113Thread ID of the current thread. 114.It Va ustack 115Userland stack of the current thread. 116.El 117.Pp 118Functions: 119.Bl -tag -width "lhist(value, min, max, step)" 120.It Fn clear "@map" 121Delete all (key, value) pairs from 122.Va @map . 123.It Fn delete "@map[key]" 124Delete the pair indexed by 125.Va key 126from 127.Va @map . 128.It Fn exit 129Terminate execution with exit code 0. 130The 131.Ic END 132probe, 133if any, 134is executed and the contents of all non-empty maps are printed. 135.It Fn hist "value" 136Increment the bucket corresponding to 137.Va value 138in a power-of-two histogram. 139.It Fn lhist "value" "min" "max" "step" 140Increment the bucket corresponding to 141.Va value 142in the linear histogram spawning between the positive value 143.Va min 144and 145.Va max 146with buckets of 147.Va step 148size. 149.It Fn print "@map" 150Print all pairs from 151.Va @map . 152.It Fn print "@map" n 153Print only the first 154.Va n 155entries in 156.Va @map . 157.It Fn printf "fmt" ... 158Print formatted string 159.Va fmt . 160.It Fn str "$N" "[index]" 161Return the string from argument 162.Va $N , 163truncated to 164.Va index 165characters (up to 64, the default) including a guaranteed NUL-terminator. 166.It Fn time timefmt 167Print timestamps using 168.Xr strftime 3 . 169.It Fn zero "@map" 170Set all values from 171.Va @map 172to 0. 173.El 174.Pp 175The following functions only work on a specific map entry. 176.Bl -tag -width "lhist(value, min, max, step)" 177.It "@map[key]" = Fn count 178Increase the stored value for 179.Va key 180by one. 181.It "@map[key]" = Fn max "value" 182Store the maximum recorded value for 183.Va key . 184.It "@map[key]" = Fn min "value" 185Store the minimum recorded value for 186.Va key . 187.It "@map[key]" = Fn sum "value" 188Store the sum of all recorded values for 189.Va key . 190.El 191.Sh SEE ALSO 192.Xr awk 1 , 193.Xr dt 4 , 194.Xr btrace 8 195.Rs 196.\"%A First Last 197.%T BPFtrace reference guide 198.%U https://github.com/iovisor/bpftrace/blob/master/docs/reference_guide.md 199.\"%D November 1, 1901 200.Re 201.Sh STANDARDS 202The dialect 203of the 204.Nm 205language described in this manual and supported by 206.Xr btrace 8 207is compatible with BPFtrace. 208The syntax is similar to 209.Xr awk 1 210and dtrace. 211