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	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
16
17	*COMMANDS* := { **pin** | **help** }
18
19ITER COMMANDS
20===================
21
22|	**bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*]
23|	**bpftool** **iter help**
24|
25|	*OBJ* := /a/file/of/bpf_iter_target.o
26|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
27
28DESCRIPTION
29===========
30	**bpftool iter pin** *OBJ* *PATH* [**map** *MAP*]
31		  A bpf iterator combines a kernel iterating of
32		  particular kernel data (e.g., tasks, bpf_maps, etc.)
33		  and a bpf program called for each kernel data object
34		  (e.g., one task, one bpf_map, etc.). User space can
35		  *read* kernel iterator output through *read()* syscall.
36
37		  The *pin* command creates a bpf iterator from *OBJ*,
38		  and pin it to *PATH*. The *PATH* should be located
39		  in *bpffs* mount. It must not contain a dot
40		  character ('.'), which is reserved for future extensions
41		  of *bpffs*.
42
43		  Map element bpf iterator requires an additional parameter
44		  *MAP* so bpf program can iterate over map elements for
45		  that map. User can have a bpf program in kernel to run
46		  with each map element, do checking, filtering, aggregation,
47		  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
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