Struct libbpf_rs::MapHandle

pub struct MapHandle { /* private fields */ }

A handle to a map. Handles can be duplicated and dropped.

While possible to created directly, in many cases it is useful to create such a handle from an existing Map:

let map: &Map = get_map();
let map_handle = MapHandle::try_clone(map).unwrap();

Some methods require working with raw bytes. You may find libraries such as plain helpful.

Implementations

impl MapHandle

pub fn create<T: AsRef<str>>( map_type: MapType, name: Option<T>, key_size: u32, value_size: u32, max_entries: u32, opts: &bpf_map_create_opts, ) -> Result<MapHandle>

Create a bpf map whose data is not managed by libbpf.

pub fn from_pinned_path<P: AsRef<Path>>(path: P) -> Result<Self>

Open a previously pinned map from its path.

Panics

If the path contains null bytes.

pub fn from_map_id(id: u32) -> Result<Self>

Open a loaded map from its map id.

pub fn try_clone(this: &MapHandle) -> Result<Self>

Try cloning this handle by duplicating its underlying file descriptor.

pub fn info(&self) -> Result<MapInfo>

Fetch extra map information

pub fn name(&self) -> &str

Retrieve the Map’s name.

pub fn map_type(&self) -> MapType

Retrieve type of the map.

pub fn key_size(&self) -> u32

Key size in bytes

pub fn value_size(&self) -> u32

Value size in bytes

pub fn lookup(&self, key: &[u8], flags: MapFlags) -> Result<Option<Vec<u8>>>

Returns map value as Vec of u8.

key must have exactly MapHandle::key_size() elements.

If the map is one of the per-cpu data structures, the function MapHandle::lookup_percpu() must be used. If the map is of type bloom_filter the function MapHandle::lookup_bloom_filter() must be used

pub fn lookup_bloom_filter(&self, value: &[u8]) -> Result<bool>

Returns if the given value is likely present in bloom_filter as bool.

value must have exactly MapHandle::value_size() elements.

pub fn lookup_percpu( &self, key: &[u8], flags: MapFlags, ) -> Result<Option<Vec<Vec<u8>>>>

Returns one value per cpu as Vec of Vec of u8 for per per-cpu maps.

For normal maps, MapHandle::lookup() must be used.

pub fn delete(&self, key: &[u8]) -> Result<()>

Deletes an element from the map.

key must have exactly MapHandle::key_size() elements.

pub fn delete_batch( &self, keys: &[u8], count: u32, elem_flags: MapFlags, flags: MapFlags, ) -> Result<()>

Deletes many elements in batch mode from the map.

keys must have exactly [MapHandle::key_size() * count] elements.

pub fn lookup_and_delete(&self, key: &[u8]) -> Result<Option<Vec<u8>>>

Same as MapHandle::lookup() except this also deletes the key from the map.

Note that this operation is currently only implemented in the kernel for MapType::Queue and MapType::Stack.

key must have exactly MapHandle::key_size() elements.

pub fn update(&self, key: &[u8], value: &[u8], flags: MapFlags) -> Result<()>

Update an element.

key must have exactly MapHandle::key_size() elements. value must have exactly MapHandle::value_size() elements.

For per-cpu maps, MapHandle::update_percpu() must be used.

pub fn update_batch( &self, keys: &[u8], values: &[u8], count: u32, elem_flags: MapFlags, flags: MapFlags, ) -> Result<()>

Updates many elements in batch mode in the map

keys must have exactly [MapHandle::key_size() * count] elements. value must have exactly [MapHandle::key_size() * count] elements

pub fn update_percpu( &self, key: &[u8], values: &[Vec<u8>], flags: MapFlags, ) -> Result<()>

Update an element in an per-cpu map with one value per cpu.

key must have exactly MapHandle::key_size() elements. value must have one element per cpu (see num_possible_cpus) with exactly MapHandle::value_size() elements each.

For per-cpu maps, MapHandle::update_percpu() must be used.

pub fn freeze(&self) -> Result<()>

Freeze the map as read-only from user space.

Entries from a frozen map can no longer be updated or deleted with the bpf() system call. This operation is not reversible, and the map remains immutable from user space until its destruction. However, read and write permissions for BPF programs to the map remain unchanged.

pub fn pin<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Pin this map to bpffs.

pub fn unpin<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Unpin this map from bpffs.

pub fn keys(&self) -> MapKeyIter<'_>

Returns an iterator over keys in this map

Note that if the map is not stable (stable meaning no updates or deletes) during iteration, iteration can skip keys, restart from the beginning, or duplicate keys. In other words, iteration becomes unpredictable.

Trait Implementations

impl AsFd for MapHandle

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl Debug for MapHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.