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

   1 ============
   2 bpftool-iter
   3 ============
   4 -------------------------------------------------------------------------------
   5 tool to create BPF iterators
   6 -------------------------------------------------------------------------------
   7
   8 :Manual section: 8
   9
  10 SYNOPSIS
  11 ========
  12
  13         **bpftool** [*OPTIONS*] **iter** *COMMAND*
  14
  15         *COMMANDS* := { **pin** | **help** }
  16
  17 ITER 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
  26 DESCRIPTION
  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
  52 OPTIONS
  53 =======
  54         .. include:: common_options.rst
  55
  56 EXAMPLES
  57 ========
  58 **# bpftool iter pin bpf_iter_netlink.o /sys/fs/bpf/my_netlink**
  59
  60 ::
  61
  62    Create a file-based bpf iterator from bpf_iter_netlink.o and pin it
  63    to /sys/fs/bpf/my_netlink
  64
  65 **# bpftool iter pin bpf_iter_hashmap.o /sys/fs/bpf/my_hashmap map id 20**
  66
  67 ::
  68
  69    Create a file-based bpf iterator from bpf_iter_hashmap.o and map with
  70    id 20, and pin it to /sys/fs/bpf/my_hashmap