---
name: "bt"
section: "5"
platform: "openbsd"
package: "man"
version: "8.0-current-20261101"
release: "OpenBSD 8.0-current (2026-11-01)"
platforms: ["openbsd"]
url: "https://new.carta.tech/bt/5"
---

# bt(5)

Bug Tracing language

## NAME

**BT** – Bug Tracing language

## SYNTAX

*probe* **/** *filter* **/** **{** *action* **}**

## DESCRIPTION

The **BT** language, also known as BPFtrace syntax, describes how to format and display information gathered from specified *probe* events.

Events are generated by the dynamic tracer [dt(4)](/dt/4.md) when an enabled *probe* is triggered. They are periodically collected by [btrace(8)](/btrace/8.md), which formats them using the corresponding *action*. If a recorded event doesn't match the optional *filter*, it will be silently ignored.

A valid **BT** source file contains at least one *probe* clause associated with an *action* statement.

## PROBE

The list of available probes may vary from system to system and can be queried with [btrace(8)](/btrace/8.md).

The special probes **BEGIN** and **END** may be used to manipulate states before the first event is recorded and after the last. They cannot be combined with any *filter*.

## FILTER

Define under which condition an event should be recorded when its related *probe* is executed. An empty *filter* means record all events.

Variable names available in filters:

- *pid*

  Process ID of the current thread.

- *tid*

  Thread ID of the current thread.

## ACTION

An action is a sequence of statements that are evaluated for each event recorded by the associated *probe*.

Variable names with special meaning:

- *$N*

  Command line argument *N* after the script name.

- *argN*

  Argument *N* of the corresponding probe.

- *comm*

  Command name of the current process.

- *cpu*

  ID of the processor that recorded the event.

- *kstack*

  Kernel stack of the current thread.

- *nsecs*

  Timestamp of the event in nanoseconds.

- *pid*

  Process ID of the current thread.

- *probe*

  Full name of the probe.

- *retval*

  Return value of the traced syscall.

- *tid*

  Thread ID of the current thread.

- *ustack*

  Userland stack of the current thread.

Functions:

- **clear**(*@map*)

  Delete all (key, value) pairs from *@map*.

- **delete**(*@map\[key\]*)

  Delete the pair indexed by *key* from *@map*.

- **exit**()

  Terminate execution with exit code 0. The **END** probe, if any, is executed and the contents of all non-empty maps are printed.

- **hist**(*value*)

  Increment the bucket corresponding to *value* in a power-of-two histogram.

- **lhist**(*value*, *min*, *max*, *step*)

  Increment the bucket corresponding to *value* in the linear histogram spawning between the positive value *min* and *max* with buckets of *step* size.

- **print**(*@map*)

  Print all pairs from *@map*.

- **print**(*@map*, *n*)

  Print only the first *n* entries in *@map*.

- **printf**(*fmt*, *...*)

  Print formatted string *fmt*.

- **str**(*$N*, *\[index\]*)

  Return the string from argument *$N*, truncated to *index* characters (up to 64, the default) including a guaranteed NUL-terminator.

- **time**(*timefmt*)

  Print timestamps using [strftime(3)](/strftime/3.md).

- **zero**(*@map*)

  Set all values from *@map* to 0.

The following functions only work on a specific map entry.

- @map\[key\] = **count**()

  Increase the stored value for *key* by one.

- @map\[key\] = **max**(*value*)

  Store the maximum recorded value for *key*.

- @map\[key\] = **min**(*value*)

  Store the minimum recorded value for *key*.

- @map\[key\] = **sum**(*value*)

  Store the sum of all recorded values for *key*.

## SEE ALSO

[awk(1)](/awk/1.md), [dt(4)](/dt/4.md), [btrace(8)](/btrace/8.md) *BPFtrace reference guide*, https://github.com/iovisor/bpftrace/blob/master/docs/reference\_guide.md.

## STANDARDS

The dialect of the **BT** language described in this manual and supported by [btrace(8)](/btrace/8.md) is compatible with BPFtrace. The syntax is similar to [awk(1)](/awk/1.md) and dtrace.