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