An eBPF map is a kernel data structure, shared with user space: it is how your program remembers a state and passes on what it observes. Without maps, an eBPF program would be mute and memoryless. This page explains what they are, the main types (hash table, array, ring buffer), and shows on a real example the kernel writing and user space reading the same map. Audience: anyone who reads or writes eBPF programs beyond simple display. Outputs captured on an Ubuntu 24.04 VM (kernel 6.8).
What you will learn
- Understand why maps are indispensable
- Distinguish the main types of maps and their use
- Read and write the same map from the kernel and from user space
- Choose between storing a state and streaming events
- Avoid the classic pitfalls (
NULLtest, contention, size)
Why does an eBPF program need maps?
An eBPF program has two strong limits. First, it keeps no memory from one trigger to the next: its local variables disappear at the end of each execution. Second, it cannot talk directly to a user-space program to deliver a result. The helper bpf_trace_printk (a function that the kernel makes available to eBPF programs) helps out for debugging, but it writes to a single shared channel, unsuitable for real work.
Maps lift both limits at once. They are memory areas managed by the kernel, persistent (they survive between triggers) and shared: the kernel program accesses them through helpers, user space through system calls. The map is the meeting point of the two worlds.
What is a map, concretely?
A map associates a key with a value, both of a fixed type defined at creation. You choose at declaration: the map type (which determines its behavior), the key size, the value size, and the maximum number of entries. From there, the program reads, writes and updates entries; user space does the same on its side.
The kernel catalog has many map types. The following table lists the most common and what they are for; choosing the type is the first decision when reading or writing a program.
| Map type | What it is for |
|---|---|
| Hash | Association key -> arbitrary value (counters per process, per IP...) |
| Array | Array indexed by integer, fixed size, very fast access |
| Per-CPU hash / array | One copy per core, to count without contention between processors |
| LRU hash | Hash table that automatically evicts the least recently used entries |
| Ring buffer | Queue to stream a flow of events to user space |
| Stack trace | Storage of call stacks, the basis of profiling |
How does the kernel write and user space read a map?
Nothing beats seeing both sides of the map. The following program counts system calls per process. The kernel accumulates in a hash map; the Python script then reads it. We use BCC, where the C program is embedded in Python. You do not need to know how to write this C: read it to spot where the map is declared, filled, then read.
from bcc import BPFfrom time import sleep
program = r"""struct key_t { char name[16]; };BPF_HASH(counter, struct key_t, u64); // the map: process name -> count
TRACEPOINT_PROBE(raw_syscalls, sys_enter) { // on every system call struct key_t key = {}; bpf_get_current_comm(&key.name, sizeof(key.name)); u64 zero = 0, *value; value = counter.lookup_or_try_init(&key, &zero); // fetch the entry, or create it if (value) // NULL test required by the verifier (*value)++; return 0;}"""b = BPF(text=program)
print("Counting system calls for 5 seconds...\n")sleep(5)
print(f"{'PROCESS':<16} {'CALLS':>8}")items = sorted(b["counter"].items(), key=lambda kv: kv[1].value)for key, value in items[-8:]: # the 8 most active print(f"{key.name.decode():<16} {value.value:>8}")The listing and the output below use the same names, so you can follow a value from the kernel program to what the terminal prints. Two key mechanisms in the kernel program:
BPF_HASH(counter, struct key_t, u64)declares the map: its name, the key type (a structure containing the process name), the value type (a 64-bit integer).lookup_or_try_initlooks for the entry for the key; if it does not exist, it creates it at zero. The returned value may be null, hence theif (value)that the verifier requires.
On the Python side, b["counter"].items() reads the same map from user space. Real output:
PROCESS CALLSsystemd 19multipathd 30sleep 5376uname 5520cat 5808bash 6430ls 7104id 10560The kernel filled the map in real time; Python read it at the end. That is exactly the role of a map: a state shared between the two sides of the boundary, without the kernel having to send each system call one by one to user space.
Should you store a state or stream a flow?
The previous example illustrates the first use. There are two, not to be confused, and the choice between them determines the map type to use.
Store a state, then read it (as above). The kernel aggregates in a hash or an array; user space periodically reads the result. Ideal for counters, statistics, lookup tables. The volume stays under control: whatever the number of events, the map only holds the summary.
Stream a flow of events. When you want to receive each event with its detail (a new process, a network connection), you use a ring buffer (literally a circular buffer). The program pushes a record into it at each event, user space consumes them as they come. It is the right structure for a flow, where direct display would not scale.
How do you inspect maps with bpftool?
As with programs, bpftool shows the maps actually present in the kernel, regardless of the tool that created them. It is the administrator's reflex when wanting to know what an eBPF tool consumes:
sudo bpftool map showEach map appears there with its identifier, its type, the size of its key and of its value, its maximum number of entries. You can also dump its content with bpftool map dump. This is precious for debugging: checking that a map fills up, or reading its state without writing code.
Security and pitfalls
Maps are shared memory, and their classic flaws come down to five points.
- Always test the return of a
lookupagainstNULL. The verifier imposes it; forgetting it is a classic cause of rejection, detailed in the eBPF verifier. - Heavily used counters: prefer a per-CPU map. When several cores increment the same entry, they get in each other's way (contention). A per-CPU map gives each core its copy; user space adds them up on reading. Throughput gains a lot.
- Size is bounded. A map has a maximum number of entries fixed at creation. A full hash refuses new keys; an LRU hash evicts the oldest instead. Choose according to the need.
- Maps consume locked memory. They occupy non-swappable RAM; on a constrained system, watch the consumption (visible in the
memlockfield ofbpftool). - A map can be "pinned". Pinning a map in
/sys/fs/bpfmakes it survive the end of the program that created it, and makes it accessible to others. Handy, but it is data sharing to secure.
Key takeaways
- A map is a kernel structure, persistent and shared with user space: the memory and the voice of the eBPF program.
- You choose its type according to use: hash/array for a state, ring buffer for a flow of events, per-CPU to count without contention.
- The kernel writes through helpers, user space reads through system calls: it is the bridge between the two worlds.
- Storing a state (counters, stats) and streaming a flow (each event) are two distinct uses.
- Always test
NULLafter alookup, and watch size and locked memory. - bpftool inspects and dumps maps without writing a line of code.
Knowledge check
Check that the essentials of this lesson are in place. The questions only cover what has just been explained here.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: The eBPF verifier: why your program is rejected
A new full quiz with random questions
Work again only on the questions you missed