.\"	$OpenBSD: bt.5,v 1.5 2020/04/23 18:36:51 mpi 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: April 23 2020 $
.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 with 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 "pid " -compact
.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
.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 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:
.Pp
.Bl -tag -width "delete(@map[key])" -compact
.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
.It Fn print "@map"
Print all pairs from
.Va @map
.It Fn printf "fmt" ...
print formatted string
.Va fmt
.It Fn time timefmt
print timestamps using
.Xr strftime 3
.It Fn zero "@map"
Set all values from
.Va @map
to 0
.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.