.\"	$OpenBSD: bt.5,v 1.1 2020/01/21 16:24:55 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: January 21 2020 $
.Dt BT 5
.Os
.Sh NAME
.Nm BT
.Nd B 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 pid
Process ID of the current thread
.It Va tid
Thread ID of the current thread
.It Va comm
Command name of the current process
.It Va nsecs
Timestamp of the event in nanoseconds
.It Va kstack
Kernel stack of the current thread
.It Va ustack
Userland stack of the current thread
.It Va argN
Argument
.Va N
of the corresponding probe
.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.