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	.. include:: common_options.rst
55
56EXAMPLES
57========
58**# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink**
59
60::
61
62   Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
63   to /sys/fs/bpf/my_netlink
64
65**# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20**
66
67::
68
69   Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
70   id 20, and pin it to /sys/fs/bpf/my_hashmap