Module ebpf_maps

Creating and using eBPF maps from userspace.

Copyright © (C) 2021, moskar

Authors: moskar (moskar.drummer@gmail.com).

Description

Creating and using eBPF maps from userspace.

This module contains an API for eBPF maps that mimics the built-in maps module.

Data Types

ebpf_map()

abstract datatype: ebpf_map()

An active eBPF map as returned by new/5.

iterator()

abstract datatype: iterator()

See http://erlang.org/doc/man/maps.html#type-iterator and iterator/1.

key()

key() = binary() | integer()

map_option()

map_option() = no_prealloc | read | write | zero_seed | prog_read | prog_write | clone | mmapable

type()

type() = unspec | hash | array | prog_array | perf_event_array | percpu_hash | percpu_array | stack_trace | cgroup_array | lru_hash | lru_percpu_hash | lpm_trie | array_of_maps | hash_of_maps | devmap | sockmap | cpumap | xskmap | sockhash | cgroup_storage | reuseport_sockarray | percpu_cgroup_storage | queue | stack | sk_storage | devmap_hash | struct_ops | ringbuf | inode_storage | task_storage

An atom used to specify the type of an eBPF map, see create_map/4

value()

value() = binary() | integer()

Function Index

close/1 Closes Map.
fd/1 Returns a File Descriptor for Map.
get/2 Returns the value associated with Key in eBPF map Map if Map contains Key.
get/3 Returns the value associated with Key in eBPF map Map if Map contains Key, otherwise returns Default.
iterator/1 Returns a map iterator Iterator that can be used by next/1 to traverse the key-value associations in a map.
new/4 Same as new/5, with default options.
new/5 Returns a new empty eBPF map.
next/1 Returns the next key-value association in Iterator and a new iterator for the remaining associations in the iterator.
put/3 Associates Key with value Value and inserts the association into map Map2.
remove/2 Removes the Key, if it exists, and its associated value from Map1 and returns a new map Map2 without key Key.
take/2 Removes Key, if it exists, and its associated value from Map1 and returns a tuple with the removed Value and the new map Map2 without key Key.
update/3 If Key exists in Map1, the old associated value is replaced by value Value.

Function Details

close/1

close(Map::ebpf_map()) -> ok | {error, atom()}

Closes Map.

fd/1

fd(Map::ebpf_map()) -> non_neg_integer()

Returns a File Descriptor for Map.

Can be used for passing a map to eBPF programs, e.g. via ebpf_kern:ld_map_fd/2.

get/2

get(Key::key(), Map::ebpf_map()) -> Value::value()

Returns the value associated with Key in eBPF map Map if Map contains Key.

See also http://erlang.org/doc/man/maps.html#get-2.

get/3

get(Key::key(), Map::ebpf_map(), Default::value()) -> value()

Returns the value associated with Key in eBPF map Map if Map contains Key, otherwise returns Default.

iterator/1

iterator(Map::ebpf_map()) -> Iterator::iterator()

Returns a map iterator Iterator that can be used by next/1 to traverse the key-value associations in a map.

new/4

new(Type::type(), KeySize::integer(), ValueSize::integer(), MaxEntries::integer()) -> Map::ebpf_map() | {error, atom()}

Same as new/5, with default options.

new/5

new(Type::type(), KeySize::integer(), ValueSize::integer(), MaxEntries::integer(), Options::[map_option()]) -> Map::ebpf_map() | {error, atom()}

Returns a new empty eBPF map.

If successful, the returned map can be used from userspace via the functions in this module, as well as shared with eBPF programs e.g. via ebpf_kern:ld_map_fd/2.

KeySize and ValueSize are given in octets.

The following Options are currently supported:

no_prealloc - The kernel will not allocate the needed memory for the map ahead of time. Defaults to false, i.e. the map is preallocated.

read - Limits userspace access to the map to read-only. Defaults to false.

write - Limits userspace access to the map to write-only. Defaults to false.

zero_seed - Initializes the map's hash function with a null seed, Which can be useful for testing. This option should not be used in production. Defaults to false.

prog_read - Limits the access to the map from eBPF programs to read-only. Defaults to false.

prog_write - Limits the access to the map from eBPF programs to write-only. Defaults to false.

next/1

next(Iterator::iterator()) -> {Key::key(), Value::value(), Iterator2::iterator()} | none

Returns the next key-value association in Iterator and a new iterator for the remaining associations in the iterator.

If Key is currently the last key in the map, none is returned.

Note: unlike Erlang/OTP built-in maps, eBPF maps can be altered by kernelspace-resident eBPF programs, hence even if this function returns none it does not mean that it will always return none.

put/3

put(Key::key(), Value::value(), Map1::ebpf_map()) -> Map2::ebpf_map()

Associates Key with value Value and inserts the association into map Map2. If key Key already exists in map Map1, the old associated value is replaced by value Value.

See also http://erlang.org/doc/man/maps.html#put-3.

remove/2

remove(Key::key(), Map1::ebpf_map()) -> Map2::ebpf_map()

Removes the Key, if it exists, and its associated value from Map1 and returns a new map Map2 without key Key.

See also http://erlang.org/doc/man/maps.html#remove-2.

take/2

take(Key::key(), Map1::ebpf_map()) -> {Value::value(), Map2::ebpf_map()} | error

Removes Key, if it exists, and its associated value from Map1 and returns a tuple with the removed Value and the new map Map2 without key Key. If the key does not exist error is returned.

See also http://erlang.org/doc/man/maps.html#take-2.

update/3

update(Key::key(), Value::value(), Map1::ebpf_map()) -> Map2::ebpf_map()

If Key exists in Map1, the old associated value is replaced by value Value. The function returns a new map Map2 containing the new associated value.

The call fails with a {badkey,Key} exception if no value is associated with Key.

See also http://erlang.org/doc/man/maps.html#update-3.


Generated by EDoc