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         *OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-d** | **--debug** } }
  16
  17         *COMMANDS* := { **pin** | **help** }
  18
  19 ITER COMMANDS
  20 ===================
  21
  22 |       **bpftool** **iter pin** *OBJ* *PATH* [**map** *MAP*]
  23 |       **bpftool** **iter help**
  24 |
  25 |       *OBJ* := /a/file/of/bpf_iter_target.o
  26 |       *MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
  27
  28 DESCRIPTION
  29 ===========
  30         **bpftool iter pin** *OBJ* *PATH* [**map** *MAP*]
  31                   A bpf iterator combines a kernel iterating of
  32                   particular kernel data (e.g., tasks, bpf_maps, etc.)
  33                   and a bpf program called for each kernel data object
  34                   (e.g., one task, one bpf_map, etc.). User space can
  35                   *read* kernel iterator output through *read()* syscall.
  36
  37                   The *pin* command creates a bpf iterator from *OBJ*,
  38                   and pin it to *PATH*. The *PATH* should be located
  39                   in *bpffs* mount. It must not contain a dot
  40                   character ('.'), which is reserved for future extensions
  41                   of *bpffs*.
  42
  43                   Map element bpf iterator requires an additional parameter
  44                   *MAP* so bpf program can iterate over map elements for
  45                   that map. User can have a bpf program in kernel to run
  46                   with each map element, do checking, filtering, aggregation,
  47                   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