1============
2bpftool-iter
3============
4-------------------------------------------------------------------------------
5tool to create BPF iterators
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13	**bpftool** [*OPTIONS*] **iter** *COMMAND*
14
15	*COMMANDS* := { **pin** | **help** }
16
17ITER COMMANDS
18===================
19
20|	**bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*]
21|	**bpftool** **iter help**
22|
23|	*OBJ* := /a/file/of/bpf_iter_target.o
24|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
25
26DESCRIPTION
27===========
28	**bpftool iter pin** *OBJ* *PATH* [**map** *MAP*]
29		  A bpf iterator combines a kernel iterating of
30		  particular kernel data (e.g., tasks, bpf_maps, etc.)
31		  and a bpf program called for each kernel data object
32		  (e.g., one task, one bpf_map, etc.). User space can
33		  *read* kernel iterator output through *read()* syscall.
34
35		  The *pin* command creates a bpf iterator from *OBJ*,
36		  and pin it to *PATH*. The *PATH* should be located
37		  in *bpffs* mount. It must not contain a dot
38		  character ('.'), which is reserved for future extensions
39		  of *bpffs*.
40
41		  Map element bpf iterator requires an additional parameter
42		  *MAP* so bpf program can iterate over map elements for
43		  that map. User can have a bpf program in kernel to run
44		  with each map element, do checking, filtering, aggregation,
45		  etc. without copying data to user space.
46
47		  User can then *cat PATH* to see the bpf iterator output.
48
49	**bpftool iter help**
50		  Print short help message.
51
52OPTIONS
53=======
54	-h, --help
55		  Print short generic help message (similar to **bpftool help**).
56
57	-V, --version
58		  Print version number (similar to **bpftool version**).
59
60	-d, --debug
61		  Print all logs available, even debug-level information. This
62		  includes logs from libbpf as well as from the verifier, when
63		  attempting to load programs.
64
65EXAMPLES
66========
67**# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink**
68
69::
70
71   Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
72   to /sys/fs/bpf/my_netlink
73
74**# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20**
75
76::
77
78   Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
79   id 20, and pin it to /sys/fs/bpf/my_hashmap
80
81SEE ALSO
82========
83	**bpf**\ (2),
84	**bpf-helpers**\ (7),
85	**bpftool**\ (8),
86	**bpftool-btf**\ (8),
87	**bpftool-cgroup**\ (8),
88	**bpftool-feature**\ (8),
89	**bpftool-gen**\ (8),
90	**bpftool-link**\ (8),
91	**bpftool-map**\ (8),
92	**bpftool-net**\ (8),
93	**bpftool-perf**\ (8),
94	**bpftool-prog**\ (8),
95	**bpftool-struct_ops**\ (8)
96