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
  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
  58 OPTIONS
  59 =======
  60         .. include:: common_options.rst
  61
  62 EXAMPLES
  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