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