bpftool-iter(8)

✨ NAME ✨

okay so bestie, this is bpftool-iter — the little corner of bpftool(8) (that's its home manual, section 8, System Manager's Manual, iykyk) that's literally just about making BPF iterators. That's the whole job. Slay.

---

🌸 SYNOPSIS 🌸

the vibe check on how you actually call it:

bpftool [OPTIONS] iter COMMAND

OPTIONS := { { -j | --json } [{ -p | --pretty }] | { -d | --debug } }

COMMANDS := { pin | help }

---

🦋 ITER COMMANDS 🦋

these are the moves you can pull 💅

bpftool iter pin OBJ PATH [map MAP]
bpftool iter help

OBJ := /a/file/of/bpf_iter_target.o
MAP := { id MAP_ID | pinned FILE }

---

💜 DESCRIPTION 💜

bpftool iter pin OBJ PATH [map MAP]

so a bpf iterator is lowkey a collab 👯 — it pairs up a kernel iterating over some specific kernel data (think tasks, bpf_maps, etc.) with a bpf program that gets called for each one of those kernel data objects (like one task, one bpf_map, etc.). and then user space can just read the kernel iterator output through the read() syscall. no cap, that's the whole tea.

the pin command creates a bpf iterator from OBJ, and pins it to PATH. and PATH has got to live inside a bpffs mount, periodt. also it must not contain a dot character (.), because that's reserved for future extensions of bpffs. so don't. 🙈

map element bpf iterators need one extra thing: the MAP parameter, so the bpf program can iterate over map elements for that map. that way you can have a bpf program in the kernel running with each map element and doing checking, filtering, aggregation, etc. — without copying data to user space. iconic behavior tbh.

and then, bestie, you just cat PATH to see the bpf iterator output. that's it. that's the moment. ✨

bpftool iter help

prints a short help message. short. sweet. 🎀

---

💅 OPTIONS 💅

• -h, --help — print a short help message (basically the same energy as bpftool help).
• -V, --version — print bpftool's version number (similar to bpftool version), plus the number of the libbpf version in use, plus any optional features that were compiled into your bpftool. and what are those optional features, you ask? 👀 things like linking against LLVM or libbfd to give you the disassembler for JIT-ted programs (bpftool prog dump jited), and usage of BPF skeletons (some features — like bpftool prog profile, or showing pids associated to BPF objects — may rely on that).
• -j, --json — generate JSON output. for commands that can't produce JSON, this option just does nothing. no harm, no foul. 🌈
• -p, --pretty — generate human-readable JSON output. and it implies -j, so you don't gotta say both.
• -d, --debug — print all the logs available, even debug-level info. that includes logs from libbpf and from the verifier, whenever it's attempting to load programs. maximum yapping mode, we love it 💀

---

🍓 EXAMPLES 🍓

watch and learn, bestie:

# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink

create a file-based bpf iterator out of bpf_iter_netlink.o and pin it to /sys/fs/bpf/my_netlink. 🫶

# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20

create a file-based bpf iterator out of bpf_iter_hashmap.o plus the map with id 20, and pin it to /sys/fs/bpf/my_hashmap. ate, no crumbs 👑

---

⭐ SEE ALSO ⭐

go read these too, they're all part of the friend group:

bpf(2), bpf-helpers(7), bpftool(8), bpftool-btf(8), bpftool-cgroup(8), bpftool-feature(8), bpftool-gen(8), bpftool-link(8), bpftool-map(8), bpftool-net(8), bpftool-perf(8), bpftool-prog(8), bpftool-struct_ops(8), bpftool-token(8)

---

and that's the whole page, babes 💖 this was the bpftool-iter(8) manual page straight out of the System Manager's Manual — same section 8, same source, same everything, just with way better vibes. mwah, go pin something 🎀🦋✨