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===========
34bpftool iter pin *OBJ* *PATH* [map *MAP*]
35    A bpf iterator combines a kernel iterating of particular kernel data (e.g.,
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 space can *read* kernel iterator
38    output through *read()* syscall.
39
40    The *pin* command creates a bpf iterator from *OBJ*, and pin it to *PATH*.
41    The *PATH* should be located in *bpffs* mount. It must not contain a dot
42    character ('.'), which is reserved for future extensions of *bpffs*.
43
44    Map element bpf iterator requires an additional parameter *MAP* so bpf
45    program can iterate over map elements for that map. User can have a bpf
46    program in kernel to run with each map element, do checking, filtering,
47    aggregation, etc. without copying data to user space.
 
 
 
 
48
49    User can then *cat PATH* to see the bpf iterator output.
50
51bpftool 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

 
 
 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)