tools/bpf/bpftool/Documentation/bpftool-iter.rst

   1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
   2
   3 ============
   4 bpftool-iter
   5 ============
   6 -------------------------------------------------------------------------------
   7 tool to create BPF iterators
   8 -------------------------------------------------------------------------------
   9
  10 :Manual section: 8
  11
  12 .. include:: substitutions.rst
  13
  14 SYNOPSIS
  15 ========
  16
  17 **bpftool** [*OPTIONS*] **iter** *COMMAND*
  18
  19 *OPTIONS* := { |COMMON_OPTIONS| }
  20
  21 *COMMANDS* := { **pin** | **help** }
  22
  23 ITER 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
  32 DESCRIPTION
  33 ===========
  34 bpftool 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
  51 bpftool iter help
  52     Print short help message.
  53
  54 OPTIONS
  55 =======
  56 .. include:: common_options.rst
  57
  58 EXAMPLES
  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