1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
3 ============
4 bpftool-iter
5 ============
6 -------------------------------------------------------------------------------
7 tool to create BPF iterators
8 -------------------------------------------------------------------------------
9
10 :Manual section: 8
11
12 .. include:: substitutions.rst
13
14 SYNOPSIS
15 ========
16
17 **bpftool** [*OPTIONS*] **iter** *COMMAND*
18
19 *OPTIONS* := { |COMMON_OPTIONS| }
20
21 *COMMANDS* := { **pin** | **help** }
22
23 ITER 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
32 DESCRIPTION
33 ===========
34 bpftool 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
51 bpftool iter help
52 Print short help message.
53
54 OPTIONS
55 =======
56 .. include:: common_options.rst
57
58 EXAMPLES
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.