1================
2bpftool-map
3================
4-------------------------------------------------------------------------------
5tool for inspection and simple manipulation of eBPF maps
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13	**bpftool** [*OPTIONS*] **map** *COMMAND*
14
15	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] | { **-f** | **--bpffs** } }
16
17	*COMMANDS* :=
18	{ **show** | **list** | **create** | **dump** | **update** | **lookup** | **getnext**
19	| **delete** | **pin** | **help** }
20
21MAP COMMANDS
22=============
23
24|	**bpftool** **map { show | list }**   [*MAP*]
25|	**bpftool** **map create**     *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE* \
26|		**entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
27|	**bpftool** **map dump**       *MAP*
28|	**bpftool** **map update**     *MAP*  **key** *DATA*   **value** *VALUE* [*UPDATE_FLAGS*]
29|	**bpftool** **map lookup**     *MAP*  **key** *DATA*
30|	**bpftool** **map getnext**    *MAP* [**key** *DATA*]
31|	**bpftool** **map delete**     *MAP*  **key** *DATA*
32|	**bpftool** **map pin**        *MAP*  *FILE*
33|	**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
34|	**bpftool** **map help**
35|
36|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
37|	*DATA* := { [**hex**] *BYTES* }
38|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
39|	*VALUE* := { *DATA* | *MAP* | *PROG* }
40|	*UPDATE_FLAGS* := { **any** | **exist** | **noexist** }
41|	*TYPE* := { **hash** | **array** | **prog_array** | **perf_event_array** | **percpu_hash**
42|		| **percpu_array** | **stack_trace** | **cgroup_array** | **lru_hash**
43|		| **lru_percpu_hash** | **lpm_trie** | **array_of_maps** | **hash_of_maps**
44|		| **devmap** | **sockmap** | **cpumap** | **xskmap** | **sockhash**
45|		| **cgroup_storage** | **reuseport_sockarray** | **percpu_cgroup_storage**
46|		| **queue** | **stack** }
47
48DESCRIPTION
49===========
50	**bpftool map { show | list }**   [*MAP*]
51		  Show information about loaded maps.  If *MAP* is specified
52		  show information only about given map, otherwise list all
53		  maps currently loaded on the system.
54
55		  Output will start with map ID followed by map type and
56		  zero or more named attributes (depending on kernel version).
57
58	**bpftool map create** *FILE* **type** *TYPE* **key** *KEY_SIZE* **value** *VALUE_SIZE*  **entries** *MAX_ENTRIES* **name** *NAME* [**flags** *FLAGS*] [**dev** *NAME*]
59		  Create a new map with given parameters and pin it to *bpffs*
60		  as *FILE*.
61
62	**bpftool map dump**    *MAP*
63		  Dump all entries in a given *MAP*.
64
65	**bpftool map update**  *MAP*  **key** *DATA*   **value** *VALUE* [*UPDATE_FLAGS*]
66		  Update map entry for a given *KEY*.
67
68		  *UPDATE_FLAGS* can be one of: **any** update existing entry
69		  or add if doesn't exit; **exist** update only if entry already
70		  exists; **noexist** update only if entry doesn't exist.
71
72		  If the **hex** keyword is provided in front of the bytes
73		  sequence, the bytes are parsed as hexadeximal values, even if
74		  no "0x" prefix is added. If the keyword is not provided, then
75		  the bytes are parsed as decimal values, unless a "0x" prefix
76		  (for hexadecimal) or a "0" prefix (for octal) is provided.
77
78	**bpftool map lookup**  *MAP*  **key** *DATA*
79		  Lookup **key** in the map.
80
81	**bpftool map getnext** *MAP* [**key** *DATA*]
82		  Get next key.  If *key* is not specified, get first key.
83
84	**bpftool map delete**  *MAP*  **key** *DATA*
85		  Remove entry from the map.
86
87	**bpftool map pin**     *MAP*  *FILE*
88		  Pin map *MAP* as *FILE*.
89
90		  Note: *FILE* must be located in *bpffs* mount. It must not
91		  contain a dot character ('.'), which is reserved for future
92		  extensions of *bpffs*.
93
94	**bpftool** **map event_pipe** *MAP* [**cpu** *N* **index** *M*]
95		  Read events from a BPF_MAP_TYPE_PERF_EVENT_ARRAY map.
96
97		  Install perf rings into a perf event array map and dump
98		  output of any bpf_perf_event_output() call in the kernel.
99		  By default read the number of CPUs on the system and
100		  install perf ring for each CPU in the corresponding index
101		  in the array.
102
103		  If **cpu** and **index** are specified, install perf ring
104		  for given **cpu** at **index** in the array (single ring).
105
106		  Note that installing a perf ring into an array will silently
107		  replace any existing ring.  Any other application will stop
108		  receiving events if it installed its rings earlier.
109
110	**bpftool map help**
111		  Print short help message.
112
113OPTIONS
114=======
115	-h, --help
116		  Print short generic help message (similar to **bpftool help**).
117
118	-v, --version
119		  Print version number (similar to **bpftool version**).
120
121	-j, --json
122		  Generate JSON output. For commands that cannot produce JSON, this
123		  option has no effect.
124
125	-p, --pretty
126		  Generate human-readable JSON output. Implies **-j**.
127
128	-f, --bpffs
129		  Show file names of pinned maps.
130
131EXAMPLES
132========
133**# bpftool map show**
134::
135
136  10: hash  name some_map  flags 0x0
137	key 4B  value 8B  max_entries 2048  memlock 167936B
138
139The following three commands are equivalent:
140
141|
142| **# bpftool map update id 10 key hex   20   c4   b7   00 value hex   0f   ff   ff   ab   01   02   03   4c**
143| **# bpftool map update id 10 key     0x20 0xc4 0xb7 0x00 value     0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c**
144| **# bpftool map update id 10 key       32  196  183    0 value       15  255  255  171    1    2    3   76**
145
146**# bpftool map lookup id 10 key 0 1 2 3**
147
148::
149
150  key: 00 01 02 03 value: 00 01 02 03 04 05 06 07
151
152
153**# bpftool map dump id 10**
154::
155
156  key: 00 01 02 03  value: 00 01 02 03 04 05 06 07
157  key: 0d 00 07 00  value: 02 00 00 00 01 02 03 04
158  Found 2 elements
159
160**# bpftool map getnext id 10 key 0 1 2 3**
161::
162
163  key:
164  00 01 02 03
165  next key:
166  0d 00 07 00
167
168|
169| **# mount -t bpf none /sys/fs/bpf/**
170| **# bpftool map pin id 10 /sys/fs/bpf/map**
171| **# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00**
172
173SEE ALSO
174========
175	**bpf**\ (2),
176	**bpf-helpers**\ (7),
177	**bpftool**\ (8),
178	**bpftool-prog**\ (8),
179	**bpftool-cgroup**\ (8),
180	**bpftool-net**\ (8),
181	**bpftool-perf**\ (8)
182