.\"	$OpenBSD: bt.5,v 1.17 2023/10/22 19:30:35 cheloha Exp $
.\"
.\" Copyright (c) 2019 Martin Pieuchot <mpi@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 22 2023 $
.Dt BT 5
.Os
.Sh NAME
.Nm BT
.Nd Bug Tracing language
.Sh SYNTAX
.D1 Ar probe Ic \&/ Ar filter Ic \&/ \&{ Ar action Ic \&}
.Sh DESCRIPTION
The
.Nm
language, also known as BPFtrace syntax, describes how to format and display
information gathered from specified
.Ar probe
events.
.Pp
Events are generated by the dynamic tracer
.Xr dt 4
when an enabled
.Ar probe
is triggered.
They are periodically collected by
.Xr btrace 8 ,
which formats them using the corresponding
.Ar action .
If a recorded event doesn't match the optional
.Ar filter ,
it will be silently ignored.
.Pp
A valid
.Nm
source file contains at least one
.Ar probe
clause associated with an
.Ar action
statement.
.Sh PROBE
The list of available probes may vary from system to system and can be queried
with
.Xr btrace 8 .
.Pp
The special probes
.Ic BEGIN
and
.Ic END
may be used to manipulate states before the first event is recorded and after
the last.
They cannot be combined with any
.Ar filter .
.Sh FILTER
Define under which condition an event should be recorded when its related
.Ar probe
is executed.
An empty
.Ar filter
means record all events.
.Pp
Variable names available in filters:
.Pp
.Bl -tag -width "kstack " -compact -offset indent
.It Va pid
Process ID of the current thread.
.It Va tid
Thread ID of the current thread.
.El
.Sh ACTION
An action is a sequence of statements that are evaluated for each event recorded
by the associated
.Ar probe .
.Pp
Variable names with special meaning:
.Pp
.Bl -tag -width "kstack " -compact -offset indent
.It Va $N
Command line argument
.Va N
after the script name.
.It Va argN
Argument
.Va N
of the corresponding probe.
.It Va comm
Command name of the current process.
.It Va cpu
ID of the processor that recorded the event.
.It Va kstack
Kernel stack of the current thread.
.It Va nsecs
Timestamp of the event in nanoseconds.
.It Va pid
Process ID of the current thread.
.It Va probe
Full name of the probe.
.It Va retval
Return value of the traced syscall.
.It Va tid
Thread ID of the current thread.
.It Va ustack
Userland stack of the current thread.
.El
.Pp
Functions:
.Bl -tag -width "lhist(value, min, max, step)"
.It Fn clear "@map"
Delete all (key, value) pairs from
.Va @map .
.It Fn delete "@map[key]"
Delete the pair indexed by
.Va key
from
.Va @map .
.It Fn exit
Terminate execution with exit code 0.
The
.Ic END
probe,
if any,
is executed and the contents of all non-empty maps are printed.
.It Fn hist "value"
Increment the bucket corresponding to
.Va value
in a power-of-two histogram.
.It Fn lhist "value" "min" "max" "step"
Increment the bucket corresponding to
.Va value
in the linear histogram spawning between the positive value
.Va min
and
.Va max
with buckets of
.Va step
size.
.It Fn print "@map"
Print all pairs from
.Va @map .
.It Fn print "@map" n
Print only the first
.Va n
entries in
.Va @map .
.It Fn printf "fmt" ...
Print formatted string
.Va fmt .
.It Fn str "$N" "[index]"
Return the string from argument
.Va $N ,
truncated to
.Va index
characters (up to 64, the default) including a guaranteed NUL-terminator.
.It Fn time timefmt
Print timestamps using
.Xr strftime 3 .
.It Fn zero "@map"
Set all values from
.Va @map
to 0.
.El
.Pp
The following functions only work on a specific map entry.
.Bl -tag -width "lhist(value, min, max, step)"
.It "@map[key]" = Fn count
Increase the stored value for
.Va key
by one.
.It "@map[key]" = Fn max "value"
Store the maximum recorded value for
.Va key .
.It "@map[key]" = Fn min "value"
Store the minimum recorded value for
.Va key .
.It "@map[key]" = Fn sum "value"
Store the sum of all recorded values for
.Va key .
.El
.Sh SEE ALSO
.Xr awk 1 ,
.Xr dt 4 ,
.Xr btrace 8
.Rs
.\"%A First Last
.%T BPFtrace reference guide
.%U https://github.com/iovisor/bpftrace/blob/master/docs/reference_guide.md
.\"%D November 1, 1901
.Re
.Sh STANDARDS
The dialect
of the
.Nm
language described in this manual and supported by
.Xr btrace 8
is compatible with BPFtrace.
The syntax is similar to
.Xr awk 1
and dtrace.