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=========== 34 **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*] 35 A bpf iterator combines a kernel iterating of 36 particular kernel data (e.g., tasks, bpf_maps, etc.) 37 and a bpf program called for each kernel data object 38 (e.g., one task, one bpf_map, etc.). User space can 39 *read* kernel iterator output through *read()* syscall. 40 41 The *pin* command creates a bpf iterator from *OBJ*, 42 and pin it to *PATH*. The *PATH* should be located 43 in *bpffs* mount. It must not contain a dot 44 character ('.'), which is reserved for future extensions 45 of *bpffs*. 46 47 Map element bpf iterator requires an additional parameter 48 *MAP* so bpf program can iterate over map elements for 49 that map. User can have a bpf program in kernel to run 50 with each map element, do checking, filtering, aggregation, 51 etc. without copying data to user space. 52 53 User can then *cat PATH* to see the bpf iterator output. 54 55 **bpftool iter help** 56 Print short help message. 57 58OPTIONS 59======= 60 .. include:: common_options.rst 61 62EXAMPLES 63======== 64**# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink** 65 66:: 67 68 Create a file-based bpf iterator from bpf_iter_netlink.o and pin it 69 to /sys/fs/bpf/my_netlink 70 71**# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20** 72 73:: 74 75 Create a file-based bpf iterator from bpf_iter_hashmap.o and map with 76 id 20, and pin it to /sys/fs/bpf/my_hashmap 77