Surface Language

Reference for the bpftrace surface as whistler bpftrace accepts it. Existing bpftrace scripts mostly run unchanged.

Probes

A probe is one or more attach specs, an optional filter predicate, and a body block:

PROBE-TYPE:TARGET [, PROBE-TYPE:TARGET ...] [/predicate/] { body }

Several specs can share one body:

kprobe:vfs_read,kprobe:vfs_write { @[probe] = count(); }

Wildcard targets attach to every matching kernel function:

kprobe:tcp_* { @ = count(); }

On kernels ≥ 5.18 these will eventually use BPF_TRACE_KPROBE_MULTI; see issue #39. Today they fall back to one perf_event_open per match, which is slower but correct.

Maps and aggregations

Map references start with @. The unnamed @ is fine; named maps use @foo. Keys go in brackets:

@              = …    # global scalar
@foo           = …    # named scalar
@[pid]         = …    # keyed
@[pid, ustack] = …    # composite key

The right-hand side is either a value or an aggregation:

String-typed composite-key slots are 16 bytes for comm and whatever size you ask for with str(ptr [, n]) / kstr(ptr [, n]) (default 64).

Built-in variables

Functions and async actions

Output

Memory and addresses

CLI parameters

Bool defaults: bare --NAME → 1, --NAME=true/--NAME=1 → 1, --NAME=false/--NAME=0 → 0. Int defaults: --NAME=N parses as an integer. Missing flag → DEFAULT.

Script configuration

A top-level config = { KEY=VALUE; KEY=VALUE } block (before any probe) sets runtime knobs. BPFTRACE_FOO, FOO, and foo are equivalent. Currently honored:

Aggregations

count, sum, avg, min, max, stats, hist, lhist. See the Maps and aggregations table above. All of these must appear on the right-hand side of @m = ….

Operators

C-style: + - * / % == != < > <= >= && || ! & | ^ << >> ~. Compound assigns: += -= *= /= %= &= |= ^=. Pre/post increment and decrement: ++ --.

Casts and struct access

((struct task_struct *)curtask)->pid
((struct sock_common *)arg0)->skc_family

A cast tags the inner expression with a struct type; the subsequent ->FIELD is resolved against the kernel's BTF for that struct. Scalar fields up to 8 bytes are supported. Nested pointer chasing (curtask->mm->mmap_lock) is not yet wired up — see the Limits table.

Control flow

if (cond) { … } else { … }

while ($i < 10) { $i += 1; }

cond ? a : b

kprobe:foo /pid == 1234/ { … }     # filter predicate

while lowers to a bounded dotimes (currently 64 iterations) with the body short-circuiting once the condition goes false. The BPF verifier requires a static upper bound on every loop, so this is unavoidable without bpf_loop() helper plumbing.

Symbolic constants

Identifiers like AF_INET, O_RDONLY, IPPROTO_TCP resolve at codegen from two sources, in order:

1. Kernel BTF BTF_KIND_ENUM / ENUM64 members. Free — Whistler harvests them once per session.
2. A small curated table of POSIX/Linux #define constants BTF doesn't carry (socket families, mode bits, open flags).

The curated entries override BTF on conflict so a kernel renaming an enum can't silently change script semantics. No #include, no C parser.

User-defined functions

fn dub($x) { return $x * 2; }

kprobe:vfs_read { @ = dub(arg2); }

Functions are inlined at the AST-to-IR boundary: each call site substitutes the body, with parameters textually replaced by the argument expressions. A few caveats follow from that approach:

• Side-effecting arguments evaluate at every reference. Don't pass nsecs into a parameter you read twice if you need it stable.
• Recursion isn't blocked; the inliner will loop forever.
• No type or return-type annotations — every value is u64.

Limits

The gaps versus upstream bpftrace, in case you hit one: