1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 2 3============ 4bpftool-iter 5============ 6------------------------------------------------------------------------------- 7tool to create BPF iterators 8------------------------------------------------------------------------------- 9 10:Manual section: 8 11 12.. include:: substitutions.rst 13 14SYNOPSIS 15======== 16 17**bpftool** [*OPTIONS*] **iter** *COMMAND* 18 19*OPTIONS* := { |COMMON_OPTIONS| } 20 21*COMMANDS* := { **pin** | **help** } 22 23ITER COMMANDS 24============= 25 26| **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*] 27| **bpftool** **iter help** 28| 29| *OBJ* := /a/file/of/bpf_iter_target.o 30| *MAP* := { **id** *MAP_ID* | **pinned** *FILE* } 31 32DESCRIPTION 33=========== 34bpftool iter pin *OBJ* *PATH* [map *MAP*] 35 A bpf iterator combines a kernel iterating of particular kernel data (e.g., 36 tasks, bpf_maps, etc.) and a bpf program called for each kernel data object 37 (e.g., one task, one bpf_map, etc.). User space can *read* kernel iterator 38 output through *read()* syscall. 39 40 The *pin* command creates a bpf iterator from *OBJ*, and pin it to *PATH*. 41 The *PATH* should be located in *bpffs* mount. It must not contain a dot 42 character ('.'), which is reserved for future extensions of *bpffs*. 43 44 Map element bpf iterator requires an additional parameter *MAP* so bpf 45 program can iterate over map elements for that map. User can have a bpf 46 program in kernel to run with each map element, do checking, filtering, 47 aggregation, etc. without copying data to user space. 48 49 User can then *cat PATH* to see the bpf iterator output. 50 51bpftool iter help 52 Print short help message. 53 54OPTIONS 55======= 56.. include:: common_options.rst 57 58EXAMPLES 59======== 60**# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink** 61 62:: 63 64 Create a file-based bpf iterator from bpf_iter_netlink.o and pin it 65 to /sys/fs/bpf/my_netlink 66 67**# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20** 68 69:: 70 71 Create a file-based bpf iterator from bpf_iter_hashmap.o and map with 72 id 20, and pin it to /sys/fs/bpf/my_hashmap 73