---
name: "bpftool-iter"
section: "8"
platform: "linux"
package: "bpf"
version: "7.3.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/bpftool-iter"
---

# bpftool-iter(8)

tool to create BPF iterators

## Name

bpftool-iter - tool to create BPF iterators

## SYNOPSIS

**bpftool** \[*OPTIONS*\] **iter** *COMMAND*

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

*COMMANDS* := { **pin** \| **help** }

## ITER COMMANDS

```
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*\]**

  A bpf iterator combines a kernel iterating of particular kernel data (e.g., tasks, bpf\_maps, etc.) and a bpf program called for each kernel data object (e.g., one task, one bpf\_map, etc.). User space can *read* kernel iterator output through *read()* syscall.

  The *pin* command creates a bpf iterator from *OBJ*, and pin it to *PATH*. The *PATH* should be located in *bpffs* mount. It must not contain a dot character ('.'), which is reserved for future extensions of *bpffs*.

  Map element bpf iterator requires an additional parameter *MAP* so bpf program can iterate over map elements for that map. User can have a bpf program in kernel to run with each map element, do checking, filtering, aggregation, etc. without copying data to user space.

  User can then *cat PATH* to see the bpf iterator output.

- **bpftool iter help**

  Print short help message.

## OPTIONS

- **-h, --help**

  Print short help message (similar to **bpftool help**).

- **-V, --version**

  Print bpftool's version number (similar to **bpftool version**), the number of the libbpf version in use, and optional features that were included when bpftool was compiled. Optional features include linking against LLVM or libbfd to provide 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 it).

- **-j, --json**

  Generate JSON output. For commands that cannot produce JSON, this option has no effect.

- **-p, --pretty**

  Generate human-readable JSON output. Implies **-j**.

- **-d, --debug**

  Print all logs available, even debug-level information. This includes logs from libbpf as well as from the verifier, when attempting to load programs.

## EXAMPLES

**# bpftool iter pin bpf\_iter\_netlink.o /sys/fs/bpf/my\_netlink**

```
Create a file-based bpf iterator from 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 from bpf_iter_hashmap.o and map with
id 20, and pin it to /sys/fs/bpf/my_hashmap
```

## SEE ALSO

[**bpf**(2)](/bpf/2.md), [**bpf-helpers**(7)](/bpf-helpers/7.md), [**bpftool**(8)](/bpftool/8.md), [**bpftool-btf**(8)](/bpftool-btf/8.md), [**bpftool-cgroup**(8)](/bpftool-cgroup/8.md), [**bpftool-feature**(8)](/bpftool-feature/8.md), [**bpftool-gen**(8)](/bpftool-gen/8.md), [**bpftool-link**(8)](/bpftool-link/8.md), [**bpftool-map**(8)](/bpftool-map/8.md), [**bpftool-net**(8)](/bpftool-net/8.md), [**bpftool-perf**(8)](/bpftool-perf/8.md), [**bpftool-prog**(8)](/bpftool-prog/8.md), [**bpftool-struct\_ops**(8)](/bpftool-struct_ops/8.md), [**bpftool-token**(8)](/bpftool-token/8.md)