0001 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002
0003 ============
0004 bpftool-iter
0005 ============
0006 -------------------------------------------------------------------------------
0007 tool to create BPF iterators
0008 -------------------------------------------------------------------------------
0009
0010 :Manual section: 8
0011
0012 .. include:: substitutions.rst
0013
0014 SYNOPSIS
0015 ========
0016
0017 **bpftool** [*OPTIONS*] **iter** *COMMAND*
0018
0019 *OPTIONS* := { |COMMON_OPTIONS| }
0020
0021 *COMMANDS* := { **pin** | **help** }
0022
0023 ITER COMMANDS
0024 ===================
0025
0026 | **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*]
0027 | **bpftool** **iter help**
0028 |
0029 | *OBJ* := /a/file/of/bpf_iter_target.o
0030 | *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
0031
0032 DESCRIPTION
0033 ===========
0034 **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*]
0035 A bpf iterator combines a kernel iterating of
0036 particular kernel data (e.g., tasks, bpf_maps, etc.)
0037 and a bpf program called for each kernel data object
0038 (e.g., one task, one bpf_map, etc.). User space can
0039 *read* kernel iterator output through *read()* syscall.
0040
0041 The *pin* command creates a bpf iterator from *OBJ*,
0042 and pin it to *PATH*. The *PATH* should be located
0043 in *bpffs* mount. It must not contain a dot
0044 character ('.'), which is reserved for future extensions
0045 of *bpffs*.
0046
0047 Map element bpf iterator requires an additional parameter
0048 *MAP* so bpf program can iterate over map elements for
0049 that map. User can have a bpf program in kernel to run
0050 with each map element, do checking, filtering, aggregation,
0051 etc. without copying data to user space.
0052
0053 User can then *cat PATH* to see the bpf iterator output.
0054
0055 **bpftool iter help**
0056 Print short help message.
0057
0058 OPTIONS
0059 =======
0060 .. include:: common_options.rst
0061
0062 EXAMPLES
0063 ========
0064 **# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink**
0065
0066 ::
0067
0068 Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
0069 to /sys/fs/bpf/my_netlink
0070
0071 **# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20**
0072
0073 ::
0074
0075 Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
0076 id 20, and pin it to /sys/fs/bpf/my_hashmap
