eBPF Library

https://docs.rs/aya/latest/aya
Admin
A library providing core functionalities for developing and interacting with eBPF programs, BTF (BPF...
Tokens:523,545
Snippets:6,225
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### SockMap Usage Example

Source: https://docs.rs/aya/latest/aya/maps/sock/struct.SockMap.html?search=

Demonstrates how to initialize a SockMap, get its file descriptor, and attach an eBPF program to it. Ensure the map and program are loaded before attachment.

```rust
use aya::maps::SockMap;
use aya::programs::SkSkb;

let intercept_ingress = SockMap::try_from(bpf.map("INTERCEPT_INGRESS").unwrap())?;
let map_fd = intercept_ingress.fd().try_clone()?;

let prog: &mut SkSkb = bpf.program_mut("intercept_ingress_packet").unwrap().try_into()?;
prog.load()?;
prog.attach(&map_fd)?;


```

--------------------------------

### PerCpuArray Usage Example

Source: https://docs.rs/aya/latest/aya/maps/array/struct.PerCpuArray.html?search=std%3A%3Avec

Demonstrates how to create, set, and get values from a PerCpuArray. This is useful for scenarios where each CPU needs to maintain its own state or counter.

```rust
use aya::maps::{PerCpuArray, PerCpuValues};
use aya::util::nr_cpus;

let mut array = PerCpuArray::try_from(bpf.map_mut("ARRAY").unwrap())?;

// set array[1] = 42 for all cpus
let nr_cpus = nr_cpus().map_err(|(_, error)| error)?;
array.set(1, PerCpuValues::try_from(vec![42u32; nr_cpus])?, 0)?;

// retrieve the values at index 1 for all cpus
let values = array.get(&1, 0)?;
assert_eq!(values.len(), nr_cpus);
for cpu_val in values.iter() {
    assert_eq!(*cpu_val, 42u32);
}
```

--------------------------------

### Lsm Program Usage Example

Source: https://docs.rs/aya/latest/aya/programs/lsm/struct.Lsm.html

This example demonstrates how to load and attach an Lsm program to a specific LSM hook using the Aya library.

```APIDOC
## Example Usage

```rust
use aya::{Ebpf, programs::Lsm, BtfError, Btf};

let btf = Btf::from_sys_fs()?;
let program: &mut Lsm = bpf.program_mut("lsm_prog").unwrap().try_into()?;
program.load("security_bprm_exec", &btf)?;
program.attach()?;
```
```

--------------------------------

### Get Syscall Prefix and Construct Syscall Name

Source: https://docs.rs/aya/latest/aya/util/fn.syscall_prefix.html

This example demonstrates how to retrieve the syscall prefix and then use it to construct a full syscall filename, such as for 'exec'. Note that this function is deprecated.

```rust
use aya::util::syscall_prefix;
let prefix = syscall_prefix().unwrap();
let syscall_fname = format!("{prefix}exec");
```

--------------------------------

### EbpfLoader::new

Source: https://docs.rs/aya/latest/aya/struct.EbpfLoader.html?search=

Creates a new EbpfLoader instance. This is the starting point for configuring and loading eBPF bytecode.

```APIDOC
## EbpfLoader::new

### Description
Creates a new loader instance.

### Method

```
pub fn new() -> Self
```
```

--------------------------------

### Getting KProbe Kind

Source: https://docs.rs/aya/latest/aya/programs/kprobe/struct.KProbe.html

Determines if the program is a kprobe (attached to function start) or a kretprobe (attached to function return).

```rust
pub fn kind(&self) -> ProbeKind
```

--------------------------------

### Creating and Pinning an FdLink

Source: https://docs.rs/aya/latest/aya/programs/links/struct.FdLink.html

Demonstrates how to attach a KProbe program, obtain an FdLink from the resulting link, and then pin it to the BPF filesystem. Ensure the parent directories exist and are on a BPF filesystem.

```rust
use aya::{Ebpf, programs::{links::FdLink, KProbe}};

let program: &mut KProbe = bpf.program_mut("intercept_wakeups").unwrap().try_into()?;
program.load()?;
let link_id = program.attach("try_to_wake_up", 0)?;
let link = program.take_link(link_id).unwrap();
let fd_link: FdLink = link.try_into().unwrap();
fd_link.pin("/sys/fs/bpf/intercept_wakeups_link").unwrap();

```

--------------------------------

### CgroupDevice Program Example

Source: https://docs.rs/aya/latest/aya/programs/cgroup_device/struct.CgroupDevice.html

Demonstrates how to load and attach a CgroupDevice program to a cgroup. Ensure the program is compiled and available, and the cgroup path is correct.

```rust
use aya::programs::{CgroupAttachMode, CgroupDevice};

let cgroup = std::fs::File::open("/sys/fs/cgroup/unified")?;
let program: &mut CgroupDevice = bpf.program_mut("cgroup_dev").unwrap().try_into()?;
program.load()?;
program.attach(cgroup, CgroupAttachMode::Single)?;
```

--------------------------------

### SIMD Slice Partitioning Example

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

Demonstrates how to partition a slice into SIMD-compatible prefix, middle, and suffix parts using `as_simd`. Useful for processing slices with SIMD operations, especially when the slice length is not a multiple of the SIMD lane count.

```rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);

```

--------------------------------

### Get Detected BPF Features

Source: https://docs.rs/aya/latest/aya/fn.features.html

Call this function to retrieve a static reference to the detected BPF features. No setup or imports are required beyond having the aya library in scope.

```rust
pub fn features() -> &'static Features
```

--------------------------------

### Loading and Attaching an Extension Program

Source: https://docs.rs/aya/latest/aya/programs/extension/struct.Extension.html

Demonstrates how to load an Extension program and attach it to replace a specific function in an existing XDP program. Requires BTF loaded for both programs.

```rust
use aya::{EbpfLoader, programs::{Xdp, XdpFlags, Extension}};

let mut bpf = EbpfLoader::new().extension("extension").load_file("app.o")?;
let prog: &mut Xdp = bpf.program_mut("main").unwrap().try_into()?;
prog.load()?;
prog.attach("eth0", XdpFlags::default())?;

let prog_fd = prog.fd().unwrap();
let prog_fd = prog_fd.try_clone().unwrap();
let ext: &mut Extension = bpf.program_mut("extension").unwrap().try_into()?;
ext.load(prog_fd, "function_to_replace")?;
ext.attach()?;
Ok::<(), aya::EbpfError>(())
```

--------------------------------

### Getting Raw Pointers Spanning the Slice

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

The `as_ptr_range` method returns a `Range` of two raw pointers, representing the start and one-past-the-end of the slice's buffer. Useful for C-style interfaces and checking pointer inclusion.

```Rust
let a = [1, 2, 3];
let x = &a[1] as *const _;
let y = &5 as *const _;

assert!(a.as_ptr_range().contains(&x));
assert!(!a.as_ptr_range().contains(&y));
```

--------------------------------

### Loading and Attaching a KProbe

Source: https://docs.rs/aya/latest/aya/programs/kprobe/struct.KProbe.html

Example of how to load a KProbe program and attach it to a specific kernel function. Ensure the program is loaded before attaching.

```rust
use aya::{Ebpf, programs::KProbe};

let program: &mut KProbe = bpf.program_mut("intercept_wakeups").unwrap().try_into()?;
program.load()?;
program.attach("try_to_wake_up", 0)?;
```

--------------------------------

### Loading and Attaching an Lsm Program

Source: https://docs.rs/aya/latest/aya/programs/lsm/struct.Lsm.html

Example of how to load and attach an Lsm program to a specific LSM hook. Ensure BTF is enabled and the kernel supports BPF LSM.

```rust
use aya::{Ebpf, programs::Lsm, BtfError, Btf};

let btf = Btf::from_sys_fs()?;
let program: &mut Lsm = btf.program_mut("lsm_prog").unwrap().try_into()?;
program.load("security_bprm_exec", &btf)?;
program.attach()?;
```

--------------------------------

### Get Element Offset in Slice

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html

Retrieves the index of an element reference within a slice. Returns None if the element is not aligned or does not point to the start of an element. Useful for extending slice iterators. Note: uses pointer arithmetic, not element comparison.

```rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));

```

--------------------------------

### Iterating over exact chunks from the end of a slice

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

Use `rchunks_exact` to get an iterator over non-overlapping slices of exactly `chunk_size` elements, starting from the end. Any remaining elements that do not form a full chunk are omitted but can be accessed via the iterator's `remainder` method.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks_exact(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.remainder(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### CpuMap Usage Example

Source: https://docs.rs/aya/latest/aya/maps/xdp/struct.CpuMap.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to load an XDP program and initialize a CpuMap for packet processing. Ensure the ELF bytes are loaded and the map is correctly configured with the maximum number of entries.

```rust
use aya::maps::xdp::CpuMap;
use aya::util::nr_cpus;

let nr_cpus = nr_cpus().unwrap() as u32;
let mut bpf = aya::EbpfLoader::new()
    .set_max_entries("CPUS", nr_cpus)
    .load(elf_bytes)
    .unwrap();
let mut cpumap = CpuMap::try_from(bpf.map_mut("CPUS").unwrap())?;
let flags = 0;
let queue_size = 2048;
for i in 0..nr_cpus {
    cpumap.set(i, queue_size, None, flags);
}

```

--------------------------------

### SchedClassifierLink Link Implementation - Get ID

Source: https://docs.rs/aya/latest/aya/programs/tc/struct.SchedClassifierLink.html

Implements the Link trait for SchedClassifierLink, providing a method to get the unique link ID.

```rust
type Id = SchedClassifierLinkId;
fn id(&self) -> Self::Id
```

--------------------------------

### Attach CgroupSock Program Example

Source: https://docs.rs/aya/latest/aya/programs/cgroup_sock/struct.CgroupSock.html?search=

Demonstrates how to load and attach a CgroupSock program to a cgroup file. Ensure the necessary file path and program name are correct.

```rust
use std::fs::File;
use aya::programs::{CgroupAttachMode, CgroupSock, CgroupSockAttachType};

let file = File::open("/sys/fs/cgroup/unified")?;
let bind: &mut CgroupSock = bpf.program_mut("bind").unwrap().try_into()?;
bind.load()?;
bind.attach(file, CgroupAttachMode::Single)?;
```

--------------------------------

### Queue Initialization and Usage Example

Source: https://docs.rs/aya/latest/aya/maps/queue/struct.Queue.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to initialize a `Queue` from an eBPF map, push elements, and pop elements. Requires the `aya` crate and a valid eBPF map named 'ARRAY'.

```rust
use aya::maps::Queue;

let mut queue = Queue::try_from(bpf.map_mut("ARRAY").unwrap())?;
queue.push(42, 0)?;
queue.push(43, 0)?;
assert_eq!(queue.pop(0)?, 42);
```

--------------------------------

### Get Slice Length

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

Use the `len` method to get the number of elements in a slice. This is a fundamental operation for understanding the size of the data.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Get Value by Key (IterableMap Trait)

Source: https://docs.rs/aya/latest/aya/maps/array/struct.Array.html?search=

Implements the `IterableMap` trait to get a value using a `u32` key, which corresponds to the array index.

```rust
fn get(&self, index: &u32) -> Result<V, MapError>
```

--------------------------------

### Initialize and Use StackTraceMap

Source: https://docs.rs/aya/latest/aya/maps/stack_trace/struct.StackTraceMap.html?search=u32+-%3E+bool

Demonstrates how to initialize a StackTraceMap from a BPF map, load kernel symbols, retrieve a stack trace by its ID, and resolve symbol names for each frame.

```rust
use aya::maps::StackTraceMap;
use aya::util::kernel_symbols;

let mut stack_traces = StackTraceMap::try_from(bpf.map("STACK_TRACES").unwrap())?;
// load kernel symbols from /proc/kallsyms
let ksyms = kernel_symbols()?;

// NOTE: you typically send stack_ids from eBPF to user space using other maps
let stack_id = 1234;
let mut stack_trace = stack_traces.get(&stack_id, 0)?;

// here we resolve symbol names using kernel symbols. If this was a user space stack (
// for example captured from a uprobe), you'd have to load the symbols using some other mechanism
// (eg loading the target binary debuginfo)
for frame in stack_trace.frames() {
    if let Some(sym) = ksyms.range(..=frame.ip).next_back().map(|(_, s)| s) {
        println!(
            "{:#x} {}\n",
            frame.ip,
            sym
        );
    } else {
        println!(
            "{:#x}\n",
            frame.ip
        );
    }
}

```

--------------------------------

### Loading and Attaching a BtfTracePoint Program

Source: https://docs.rs/aya/latest/aya/programs/tp_btf/struct.BtfTracePoint.html

Example of how to load and attach a BtfTracePoint program to a kernel tracepoint. Ensure Btf::from_sys_fs() is available and the program name matches an existing tracepoint.

```rust
use aya::{Ebpf, programs::BtfTracePoint, BtfError, Btf};

let btf = Btf::from_sys_fs()?;
let program: &mut BtfTracePoint = bpf.program_mut("sched_process_fork").unwrap().try_into()?;
program.load("sched_process_fork", &btf)?;
program.attach()?;
```

--------------------------------

### Get First Chunk of Slice as Array

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

Use `first_chunk::<N>` to get a reference to the first `N` items of a slice as an array. Returns `None` if the slice is shorter than `N`.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

--------------------------------

### Example: Opening and Reading Perf Events

Source: https://docs.rs/aya/latest/aya/maps/perf/struct.AsyncPerfEventArray.html

Demonstrates how to open a perf buffer for each CPU and asynchronously read events. This snippet requires the 'async_tokio' or 'async_std' feature flags.

```rust
use aya::maps::perf::{AsyncPerfEventArray, PerfBufferError};
use aya::util::online_cpus;
use bytes::BytesMut;
use tokio::task; // or async_std::task

// try to convert the PERF_ARRAY map to an AsyncPerfEventArray
let mut perf_array = AsyncPerfEventArray::try_from(bpf.take_map("PERF_ARRAY").unwrap())?;

for cpu_id in online_cpus().map_err(|(_, error)| error)? {
    // open a separate perf buffer for each cpu
    let mut buf = perf_array.open(cpu_id, None)?;

    // process each perf buffer in a separate task
    task::spawn(async move {
        let mut buffers = (0..10)
            .map(|_| BytesMut::with_capacity(1024))
            .collect::<Vec<_>>();

        loop {
            // wait for events
            let events = buf.read_events(&mut buffers).await?;

            // events.read contains the number of events that have been read,
            // and is always <= buffers.len()
            for i in 0..events.read {
                let buf = &mut buffers[i];
                // process buf
            }
        }

        Ok::<_, PerfBufferError>(())
    });
}


```

--------------------------------

### Loading and Attaching an FExit Program

Source: https://docs.rs/aya/latest/aya/programs/fexit/struct.FExit.html

Example of how to load and attach an FExit program to a specific kernel function. Ensure BTF information is available for the running kernel.

```rust
use aya::{Ebpf, programs::FExit, BtfError, Btf};

let btf = Btf::from_sys_fs()?;
let program: &mut FExit = bpf.program_mut("filename_lookup").unwrap().try_into()?;
program.load("filename_lookup", &btf)?;
program.attach()?;
```

--------------------------------

### Get Slice Length

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Returns the number of elements in the slice.

```rust
pub fn len(&self) -> usize
```

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Example Search: Option<T>, (T -> U) -> Option<U>

Source: https://docs.rs/aya/latest/aya/fn.features.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates a common search pattern for function signatures involving Option types and transformations.

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### starts_with

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Checks if the slice starts with a given prefix slice.

```APIDOC
## starts_with(&self, needle: &[T]) -> bool

### Description
Returns `true` if `needle` is a prefix of the slice or equal to the slice.

### Method
`starts_with`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

### Response
#### Success Response
- `bool`: `true` if the slice starts with the `needle`, `false` otherwise.

#### Response Example
```json
true
// or
false
```
```

--------------------------------

### nr_cpus

Source: https://docs.rs/aya/latest/aya/util/fn.nr_cpus.html

Gets the number of possible CPUs on the system by reading from `/sys/devices/system/cpu/possible`.

```APIDOC
## Function nr_cpus

### Description
Get the number of possible cpus.
See `/sys/devices/system/cpu/possible`.

### Signature
```rust
pub fn nr_cpus() -> Result<usize, (&'static str, Error)>
```

### Returns
A `Result` containing the number of CPUs as a `usize` on success, or an error tuple on failure.
```

--------------------------------

### Loading and Attaching CgroupSockopt Program

Source: https://docs.rs/aya/latest/aya/programs/cgroup_sockopt/struct.CgroupSockopt.html

Example of loading a CgroupSockopt program and attaching it to a cgroup file. Ensure the program is loaded before attaching.

```rust
use std::fs::File;
use aya::programs::{CgroupAttachMode, CgroupSockopt};

let file = File::open("/sys/fs/cgroup/unified")?;
let program: &mut CgroupSockopt = bpf.program_mut("cgroup_sockopt").unwrap().try_into()?;
program.load()?;
program.attach(file, CgroupAttachMode::Single)?;
```

--------------------------------

### Initialize and Use XskMap

Source: https://docs.rs/aya/latest/aya/maps/xdp/struct.XskMap.html?search=

Demonstrates how to initialize an XskMap from a BPF map and set an AF_XDP socket at a specific index. The socket_fd must be the RawFd of an AF_XDP socket.

```rust
use aya::maps::XskMap;

let mut xskmap = XskMap::try_from(bpf.map_mut("SOCKETS").unwrap())?;
// socket_fd is the RawFd of an AF_XDP socket
xskmap.set(0, socket_fd, 0);
```

--------------------------------

### TypeId

Source: https://docs.rs/aya/latest/aya/programs/xdp/struct.Xdp.html

Gets the `TypeId` of `self`. This method is part of the `Any` trait implementation for `T`.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
- **TypeId**: The type identifier of the object.
```

--------------------------------

### Get SchedClassifierLink Attach Type

Source: https://docs.rs/aya/latest/aya/programs/tc/struct.SchedClassifierLink.html

Retrieves the attach type of the SchedClassifierLink.

```rust
pub fn attach_type(&self) -> Result<TcAttachType, ProgramError>
```

--------------------------------

### iter

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Returns an iterator over the slice, yielding all items from start to end.

```APIDOC
## pub fn iter(&self) -> Iter<'_, T>

### Description
Returns an iterator over the slice. The iterator yields all items from start to end.

### Method
`iter()`

### Response
- `Iter<'_, T>`: An iterator over the elements of the slice.
```

--------------------------------

### Attaching PerfEvent to CPU Clock

Source: https://docs.rs/aya/latest/aya/programs/perf_event/struct.PerfEvent.html?search=

Example demonstrating how to attach a PerfEvent program to observe CPU clock events on all online CPUs. Requires Aya and specific perf event IDs.

```rust
use aya::util::online_cpus;
use aya::programs::perf_event::
    perf_sw_ids::PERF_COUNT_SW_CPU_CLOCK,
    PerfEvent,
    PerfEventScope,
    PerfTypeId,
    SamplePolicy,
;

let prog: &mut PerfEvent = bpf.program_mut("observe_cpu_clock").unwrap().try_into()?;
prog.load()?;

for cpu in online_cpus().map_err(|(_, error)| error)? {
    prog.attach(
        PerfTypeId::Software,
        PERF_COUNT_SW_CPU_CLOCK as u64,
        PerfEventScope::AllProcessesOneCpu { cpu },
        SamplePolicy::Period(1000000),
        true,
    )?;
}
```

--------------------------------

### Stack Conversion and Pinning

Source: https://docs.rs/aya/latest/aya/maps/stack/struct.Stack.html

Details on how to create a Stack map from an existing `Map` and how to pin it to the BPF filesystem.

```APIDOC
## Stack Conversion and Pinning

### `try_from(map: &'a Map) -> Result<Stack<&'a MapData, V>, MapError>`

Attempts to create a `Stack` from an immutable reference to a `Map`.

### `try_from(map: &'a mut Map) -> Result<Stack<&'a mut MapData, V>, MapError>`

Attempts to create a `Stack` from a mutable reference to a `Map`.

### `try_from(map: Map) -> Result<Stack<MapData, V>, MapError>`

Attempts to create a `Stack` from an owned `Map`.

### `pin<P: AsRef<Path>>(self, path: P) -> Result<(), PinError>`

Pins the map to a BPF filesystem at the specified path. The map will persist until the pinned file is deleted. Parent directories must exist.
```

--------------------------------

### Get File Descriptor for PerfEventArrayBuffer

Source: https://docs.rs/aya/latest/aya/maps/perf/struct.PerfEventArrayBuffer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Borrows the file descriptor associated with the PerfEventArrayBuffer.

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

--------------------------------

### Example Search: u32 to bool

Source: https://docs.rs/aya/latest/aya/fn.features.html?search=std%3A%3Avec

Illustrates a search query for type conversions from 'u32' to 'bool'. Useful for finding functions that perform such transformations.

```rust
u32 -> bool
```

--------------------------------

### iter

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=std%3A%3Avec

Returns an iterator over the elements of the slice, yielding items from start to end.

```APIDOC
## pub fn iter(&self) -> Iter<'_, T>

### Description
Returns an iterator over the slice. The iterator yields all items from start to end.

### Returns
- `Iter<'_, T>`: An iterator over the elements of the slice.
```

--------------------------------

### Get Memory Locked

Source: https://docs.rs/aya/latest/aya/programs/struct.ProgramInfo.html?search=u32+-%3E+bool

Retrieves the amount of memory in bytes allocated and locked for the program.

```rust
pub fn memory_locked(&self) -> Result<u32, ProgramError>
```

--------------------------------

### FExit Program Lifecycle

Source: https://docs.rs/aya/latest/aya/programs/fexit/struct.FExit.html?search=std%3A%3Avec

Demonstrates the basic usage of an FExit program, including loading, attaching, and detaching.

```APIDOC
## FExit Program Usage

### Description
This example shows how to load, attach, and detach an FExit program. It requires BTF information for the running kernel.

### Example
```rust
use aya::{Ebpf, programs::FExit, BtfError, Btf};

// Assume 'bpf' is an initialized Ebpf instance
let btf = Btf::from_sys_fs()?;
let mut program: FExit = bpf.program_mut("your_program_name")?.try_into()?;

// Load the program to be attached to a specific kernel function
program.load("target_kernel_function", &btf)?;

// Attach the program to the kernel function's exit point
let link_id = program.attach()?;

// ... perform operations ...

// Detach the program using the link ID
program.detach(link_id)?;
```

### Methods
- `load(fn_name: &str, btf: &Btf)`: Loads the program to be executed when the kernel function `fn_name` is exited.
- `attach()`: Attaches the loaded program to the kernel.
- `detach(link_id: FExitLinkId)`: Detaches the program using its link ID.
```

--------------------------------

### Get BTF ID

Source: https://docs.rs/aya/latest/aya/programs/struct.ProgramInfo.html?search=u32+-%3E+bool

Retrieves the BTF ID for the program. Introduced in kernel v5.0.

```rust
pub fn btf_id(&self) -> Option<u32>
```

--------------------------------

### StackTraceMap Usage Example

Source: https://docs.rs/aya/latest/aya/maps/stack_trace/struct.StackTraceMap.html?search=

Demonstrates how to initialize a StackTraceMap, retrieve stack traces by ID, and resolve kernel symbols for each frame. Assumes stack IDs are sent from eBPF.

```rust
use aya::maps::StackTraceMap;
use aya::util::kernel_symbols;

let mut stack_traces = StackTraceMap::try_from(bpf.map("STACK_TRACES").unwrap())?;
// load kernel symbols from /proc/kallsyms
let ksyms = kernel_symbols()?;

// NOTE: you typically send stack_ids from eBPF to user space using other maps
let stack_id = 1234;
let mut stack_trace = stack_traces.get(&stack_id, 0)?;

// here we resolve symbol names using kernel symbols. If this was a user space stack (for
// example captured from a uprobe), you'd have to load the symbols using some other mechanism
// (eg loading the target binary debuginfo)
for frame in stack_trace.frames() {
    if let Some(sym) = ksyms.range(..=frame.ip).next_back().map(|(_, s)| s) {
        println!(
            "{:#x} {}",
            frame.ip,
            sym
        );
    } else {
        println!(
            "{:#x}",
            frame.ip
        );
    }
}

```

--------------------------------

### Get Program Type

Source: https://docs.rs/aya/latest/aya/programs/struct.ProgramInfo.html?search=u32+-%3E+bool

Retrieves the type of the eBPF program. Introduced in kernel v4.13.

```rust
pub fn program_type(&self) -> Result<ProgramType, ProgramError>
```

--------------------------------

### Btf::new

Source: https://docs.rs/aya/latest/aya/struct.Btf.html?search=

Creates a new, empty Btf instance with its header initialized. This is the starting point for building BTF metadata programmatically.

```APIDOC
## Btf::new

### Description
Creates a new empty instance with its header initialized.

### Method
`new()`

### Returns
- `Btf`: A new, empty Btf instance.
```

--------------------------------

### Get LircLink Identifier

Source: https://docs.rs/aya/latest/aya/programs/lirc_mode2/struct.LircLink.html

Returns the unique identifier for the LircLink. The type of the identifier is LircLinkId.

```rust
type Id = LircLinkId;
fn id(&self) -> Self::Id
```

--------------------------------

### Initialize and Use DevMapHash

Source: https://docs.rs/aya/latest/aya/maps/xdp/struct.DevMapHash.html

Demonstrates how to initialize a DevMapHash from a BPF map and insert a redirection rule. This is useful for setting up traffic redirection policies within an XDP program.

```rust
use aya::maps::xdp::DevMapHash;

let mut devmap = DevMapHash::try_from(bpf.map_mut("IFACES").unwrap())?;
// Lookups with key 2 will redirect packets to interface with index 3 (e.g. eth1)
devmap.insert(2, 3, None, 0);

```

--------------------------------

### Type ID Implementation

Source: https://docs.rs/aya/latest/aya/programs/extension/struct.ExtensionLink.html

Implements the Any trait, providing a method to get the TypeId of an object.

```rust
impl<T> Any for T where T: 'static + ?Sized {
    fn type_id(&self) -> TypeId {
        // ... implementation details ...
    }
}
```

--------------------------------

### Load and Attach KProbe Program

Source: https://docs.rs/aya/latest/aya/programs/index.html?search=

Demonstrates loading an eBPF object file and attaching a KProbe program to a kernel function. Ensure the program name and kernel function name are correct.

```rust
use aya::{Ebpf, programs::KProbe};

let mut bpf = Ebpf::load_file("ebpf_programs.o")?;
// intercept_wakeups is the name of the program we want to load
let program: &mut KProbe = bpf.program_mut("intercept_wakeups").unwrap().try_into()?;
program.load()?;
// intercept_wakeups will be called every time try_to_wake_up() is called
// inside the kernel
program.attach("try_to_wake_up", 0)?;
```

--------------------------------

### get

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Retrieves a reference to an element or subslice by index. Returns None if the index is out of bounds.

```APIDOC
## pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.

### Method
`get(index)`

### Parameters
- `index`: `I` where `I: SliceIndex<[T]>` - The index or range to access.

### Response
- `Option<&<I as SliceIndex<[T]>>::Output>`: A reference to the element or subslice, or `None` if the index is out of bounds.
```

--------------------------------

### Get Raw File Descriptor for PerfEventArrayBuffer

Source: https://docs.rs/aya/latest/aya/maps/perf/struct.PerfEventArrayBuffer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Extracts the raw file descriptor from the PerfEventArrayBuffer.

```rust
fn as_raw_fd(&self) -> RawFd
```

--------------------------------

### Pinning an FdLink to a BPF Filesystem

Source: https://docs.rs/aya/latest/aya/programs/links/struct.FdLink.html

Shows how to take an owned link, convert it to an FdLink, and then pin it to a specified path. The parent directories must exist and be on a BPF filesystem.

```rust
let link_id = prog.attach()?;
let owned_link = prog.take_link(link_id)?;
let fd_link: FdLink = owned_link.into();
let pinned_link = fd_link.pin("/sys/fs/bpf/example")?;

```

--------------------------------

### Get LsmLink ID

Source: https://docs.rs/aya/latest/aya/programs/lsm/struct.LsmLink.html

Implements the Link trait for LsmLink, providing the unique ID of the link.

```rust
type Id = LsmLinkId;
fn id(&self) -> Self::Id
```

--------------------------------

### Loading and Attaching SkLookup Program

Source: https://docs.rs/aya/latest/aya/programs/sk_lookup/struct.SkLookup.html

Example of how to load and attach an SkLookup program to a network namespace. Requires opening a file representing the network namespace and then loading and attaching the program.

```rust
use std::fs::File;
use aya::programs::SkLookup;

let file = File::open("/var/run/netns/test")?;
let program: &mut SkLookup = bpf.program_mut("sk_lookup").unwrap().try_into()?;
program.load()?;
program.attach(file)?;
```

--------------------------------

### get

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html

Returns a reference to an element or subslice based on the provided index. Handles bounds checking.

```APIDOC
## pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

### Description
Returns a reference to an element or subslice based on the provided index. Handles bounds checking.

### Parameters
#### Path Parameters
- **index** (I: SliceIndex<[T]>) - The index or range to access.

### Response
#### Success Response
- **Option<&<I as SliceIndex<[T]>>::Output>** - A reference to the element or subslice, or None if the index is out of bounds.
```

--------------------------------

### Loading and Attaching a TracePoint Program

Source: https://docs.rs/aya/latest/aya/programs/trace_point/struct.TracePoint.html

Demonstrates how to load a TracePoint program and attach it to a specific kernel trace point. Ensure the 'sched' category and 'sched_switch' event are available on your system.

```rust
use aya::programs::TracePoint;

let prog: &mut TracePoint = bpf.program_mut("trace_context_switch").unwrap().try_into()?;
prog.load()?;
prog.attach("sched", "sched_switch")?;
```

--------------------------------

### as_array

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Attempts to get a reference to the underlying array if its length matches the specified size N.

```APIDOC
## pub fn as_array<const N: usize>(&self) -> Option<&[T; N]>

### Description
Gets a reference to the underlying array. If `N` is not exactly equal to the length of `self`, then this method returns `None`.

### Method
`as_array::<N>()`

### Parameters
- `N`: `usize` - The expected size of the array.

### Response
- `Option<&[T; N]>`: A reference to the underlying array if its length matches `N`, otherwise `None`.
```

--------------------------------

### Btf::new

Source: https://docs.rs/aya/latest/aya/struct.Btf.html

Creates a new, empty instance of Btf with its header initialized. This is the starting point for manually constructing BTF metadata.

```APIDOC
## Btf::new

### Description
Creates a new, empty instance of Btf with its header initialized.

### Method
`new()`

### Returns
- `Btf` - A new, empty Btf instance.
```

--------------------------------

### Attach Program with LinkOrder

Source: https://docs.rs/aya/latest/aya/programs/links/struct.LinkOrder.html

Demonstrates attaching a program with a specific link order using LinkOrder::first(). Requires aya and relevant program types.

```rust
use aya::programs::{tc, SchedClassifier, TcAttachType, tc::TcAttachOptions, LinkOrder};

let prog: &mut SchedClassifier = bpf.program_mut("redirect_ingress").unwrap().try_into()?;
prog.load()?;
let options = TcAttachOptions::TcxOrder(LinkOrder::first());
prog.attach_with_options("eth0", TcAttachType::Ingress, options)?;
```

--------------------------------

### Get Last Element of Slice

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Returns the last element of the slice, or None if the slice is empty.

```rust
pub fn last(&self) -> Option<&T>
```

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### Initialize and Use Stack Map

Source: https://docs.rs/aya/latest/aya/maps/stack/struct.Stack.html

Demonstrates how to initialize a Stack map from a BPF map and perform push and pop operations. Requires the 'STACK' map to be defined in the BPF program.

```rust
use aya::maps::Stack;

let mut stack = Stack::try_from(bpf.map_mut("STACK").unwrap())?;
stack.push(42, 0)?;
stack.push(43, 0)?;
assert_eq!(stack.pop(0)?, 43);
```

--------------------------------

### Get First Element of Slice

Source: https://docs.rs/aya/latest/aya/maps/ring_buf/struct.RingBufItem.html?search=

Returns the first element of the slice, or None if the slice is empty.

```rust
pub fn first(&self) -> Option<&T>
```

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### Get Map Type

Source: https://docs.rs/aya/latest/aya/maps/struct.MapInfo.html?search=u32+-%3E+bool

Retrieves the type of the eBPF map. Requires kernel v4.13 or later.

```rust
pub fn map_type(&self) -> Result<MapType, MapError>
```

--------------------------------

### PerfEventArray Usage Example

Source: https://docs.rs/aya/latest/aya/maps/perf/struct.PerfEventArray.html

Demonstrates a common pattern for using PerfEventArray by opening a buffer for each online CPU and polling for events. Ensure proper error handling for online_cpus and map operations.

```rust
use aya::maps::PerfEventArray;
use aya::util::online_cpus;
use bytes::BytesMut;

let mut perf_array = PerfEventArray::try_from(bpf.map_mut("EVENTS").unwrap())?;

// eBPF programs are going to write to the EVENTS perf array, using the id of the CPU they're
// running on as the array index.
let mut perf_buffers = Vec::new();
for cpu_id in online_cpus().map_err(|(_, error)| error)? {
    // this perf buffer will receive events generated on the CPU with id cpu_id
    perf_buffers.push(perf_array.open(cpu_id, None)?);
}

let mut out_bufs = [BytesMut::with_capacity(1024)];

// poll the buffers to know when they have queued events
let poll = poll_buffers(perf_buffers);
loop {
    for read_buf in poll.poll_readable() {
        read_buf.read_events(&mut out_bufs)?;
        // process out_bufs
    }
}

```

--------------------------------

### Load and Attach SockOps Program

Source: https://docs.rs/aya/latest/aya/programs/sock_ops/struct.SockOps.html?search=std%3A%3Avec

Example of loading a SockOps program and attaching it to a cgroup. Ensure the program is named 'intercept_active_sockets' and the cgroup path is correct.

```rust
use std::fs::File;
use aya::programs::{CgroupAttachMode, SockOps};

let file = File::open("/sys/fs/cgroup/unified")?;
let prog: &mut SockOps = bpf.program_mut("intercept_active_sockets").unwrap().try_into()?;
prog.load()?;
prog.attach(file, CgroupAttachMode::Single)?;
```

--------------------------------

### IterableMap::get

Source: https://docs.rs/aya/latest/aya/maps/array/struct.PerCpuArray.html?search=u32+-%3E+bool

Get the value for the provided key from the map. This is part of the `IterableMap` trait implementation.

```APIDOC
## IterableMap::get

### Description
Get the value for the provided `key`.

### Method
`get(&self, index: &u32) -> Result<PerCpuValues<V>, MapError>`
```

--------------------------------

### Loading and Attaching a CgroupSockAddr Program

Source: https://docs.rs/aya/latest/aya/programs/cgroup_sock_addr/struct.CgroupSockAddr.html

Example of loading a CgroupSockAddr program and attaching it to a cgroup file. Ensure the program is compiled and available, and the cgroup path is correct.

```rust
use std::fs::File;
use aya::programs::{CgroupAttachMode, CgroupSockAddr, CgroupSockAddrAttachType};

let file = File::open("/sys/fs/cgroup/unified")?;
let egress: &mut CgroupSockAddr = bpf.program_mut("connect4").unwrap().try_into()?;
egress.load()?;
egress.attach(file, CgroupAttachMode::Single)?;
```

--------------------------------

### Any::type_id Implementation

Source: https://docs.rs/aya/latest/aya/enum.EbpfError.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the TypeId of the implementing type. This is part of the Any trait for trait object introspection.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Load and Attach CgroupSkb Program

Source: https://docs.rs/aya/latest/aya/programs/cgroup_skb/struct.CgroupSkb.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to load a CgroupSkb program and attach it to a cgroup for egress filtering. Ensure the program is correctly identified (e.g., 'egress_filter') and the cgroup path is valid.

```rust
use std::fs::File;
use aya::programs::{CgroupAttachMode, CgroupSkb, CgroupSkbAttachType};

let file = File::open("/sys/fs/cgroup/unified")?;
let egress: &mut CgroupSkb = bpf.program_mut("egress_filter").unwrap().try_into()?;
egres.load()?;
egres.attach(file, CgroupSkbAttachType::Egress, CgroupAttachMode::Single)?;
```

--------------------------------

### VerifierLogLevel::empty()

Source: https://docs.rs/aya/latest/aya/struct.VerifierLogLevel.html?search=std%3A%3Avec

Creates a VerifierLogLevel instance with all bits unset. Useful for starting with no flags enabled.

```rust
pub const fn empty() -> Self
```

--------------------------------

### Get SkLookupLink ID

Source: https://docs.rs/aya/latest/aya/programs/sk_lookup/struct.SkLookupLink.html

Implements the Link trait to provide an ID for the SkLookupLink. The ID type is SkLookupLinkId.

```rust
type Id = SkLookupLinkId;
fn id(&self) -> Self::Id
```

--------------------------------

### Loading a CgroupSock Program

Source: https://docs.rs/aya/latest/aya/programs/cgroup_sock/struct.CgroupSock.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates loading a CgroupSock program into the kernel. This is a prerequisite before attaching the program to a cgroup.

```rust
bind.load()?;
```

--------------------------------

### PerfEventArray Usage Example

Source: https://docs.rs/aya/latest/aya/maps/perf/struct.PerfEventArray.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates a common pattern for using PerfEventArray by creating a separate buffer for each online CPU and polling them for events. Ensure you have a polling mechanism (like epoll or mio) and handle event processing appropriately.

```rust
use aya::maps::PerfEventArray;
use aya::util::online_cpus;
use bytes::BytesMut;

let mut perf_array = PerfEventArray::try_from(bpf.map_mut("EVENTS").unwrap())?;

// eBPF programs are going to write to the EVENTS perf array, using the id of the CPU they're
// running on as the array index.
let mut perf_buffers = Vec::new();
for cpu_id in online_cpus().map_err(|(_, error)| error)? {
    // this perf buffer will receive events generated on the CPU with id cpu_id
    perf_buffers.push(perf_array.open(cpu_id, None)?);
}

let mut out_bufs = [BytesMut::with_capacity(1024)];

// poll the buffers to know when they have queued events
let poll = poll_buffers(perf_buffers);
loop {
    for read_buf in poll.poll_readable() {
        read_buf.read_events(&mut out_bufs)?;
        // process out_bufs
    }
}
```

--------------------------------

### Get ExtensionLink ID

Source: https://docs.rs/aya/latest/aya/programs/extension/struct.ExtensionLink.html

Implements the Link trait to provide a method for retrieving the unique ID of an ExtensionLink.

```rust
impl Link for ExtensionLink {
    type Id = ExtensionLinkId;

    fn id(&self) -> Self::Id {
        // ... implementation details ...
    }
}
```

--------------------------------

### Get Map ID

Source: https://docs.rs/aya/latest/aya/maps/struct.MapInfo.html?search=u32+-%3E+bool

Retrieves the unique identifier for the eBPF map. Requires kernel v4.13 or later.

```rust
pub fn id(&self) -> u32
```

--------------------------------

### PerCpuHashMap Usage Example

Source: https://docs.rs/aya/latest/aya/maps/hash_map/struct.PerCpuHashMap.html?search=std%3A%3Avec

Demonstrates how to retrieve per-CPU values for a given key from a PerCpuHashMap. Ensure the map is correctly initialized and accessible.

```rust
use aya::maps::PerCpuHashMap;

const CPU_IDS: u8 = 1;
const WAKEUPS: u8 = 2;

let mut hm = PerCpuHashMap::<_, u8, u32>::try_from(bpf.map_mut("PER_CPU_STORAGE").unwrap())?;
let cpu_ids = unsafe { hm.get(&CPU_IDS, 0)? };
let wakeups = unsafe { hm.get(&WAKEUPS, 0)? };
for (cpu_id, wakeups) in cpu_ids.iter().zip(wakeups.iter()) {
    println!("cpu {} woke up {} times", cpu_id, wakeups);
}
```

--------------------------------

### Ebpf::program_mut

Source: https://docs.rs/aya/latest/aya/struct.Ebpf.html?search=u32+-%3E+bool

Returns a mutable reference to the program with the given name. Used to get a program before loading and attaching it.

```APIDOC
## Ebpf::program_mut(&mut self, name: &str) -> Option<&mut Program>

### Description
Returns a mutable reference to the program with the given name. Used to get a program before loading and attaching it.

### Parameters
#### Path Parameters
- **name** (&str) - Required - The name of the program to retrieve.

### Returns
- Option<&mut Program> - An Option containing a mutable reference to the Program if found, otherwise None.

### Examples
```
use aya::programs::UProbe;

let program: &mut UProbe = bpf.program_mut("SSL_read").unwrap().try_into()?;
program.load()?;
program.attach(Some("SSL_read"), 0, "libssl", None)?;
```
```

--------------------------------

### Using ProgramArray for Tail Calls

Source: https://docs.rs/aya/latest/aya/maps/array/struct.ProgramArray.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This example demonstrates how to initialize a ProgramArray and set jump targets for eBPF programs using `bpf_tail_call`. It requires programs like `example_prog_0`, `example_prog_1`, and `example_prog_2` to be loaded.

```rust
use aya::maps::ProgramArray;
use aya::programs::CgroupSkb;

let mut prog_array = ProgramArray::try_from(bpf.take_map("JUMP_TABLE").unwrap())?;
let prog_0: &CgroupSkb = bpf.program("example_prog_0").unwrap().try_into()?;
let prog_0_fd =  prog_0.fd().unwrap();
let prog_1: &CgroupSkb = bpf.program("example_prog_1").unwrap().try_into()?;
let prog_1_fd = prog_1.fd().unwrap();
let prog_2: &CgroupSkb = bpf.program("example_prog_2").unwrap().try_into()?;
let prog_2_fd = prog_2.fd().unwrap();
let flags = 0;

// bpf_tail_call(ctx, JUMP_TABLE, 0) will jump to prog_0
prog_array.set(0, &prog_0_fd, flags);

// bpf_tail_call(ctx, JUMP_TABLE, 1) will jump to prog_1
prog_array.set(1, &prog_1_fd, flags);

// bpf_tail_call(ctx, JUMP_TABLE, 2) will jump to prog_2
prog_array.set(2, &prog_2_fd, flags);
```

--------------------------------

### Ebpf::program_mut

Source: https://docs.rs/aya/latest/aya/struct.Ebpf.html

Returns a mutable reference to the program with the given name. Used to get a program before loading and attaching it.

```APIDOC
## pub fn program_mut(&mut self, name: &str) -> Option<&mut Program>

### Description
Returns a mutable reference to the program with the given name.
Used to get a program before loading and attaching it. For more details on programs and their usage, see the programs module documentation.

### Parameters
#### Path Parameters
- **name** (&str) - Required - The name of the program to retrieve.

### Response
#### Success Response (Option<&mut Program>)
- Returns `Some(&mut Program)` if a program with the given name exists, otherwise `None`.

### Examples
```rust
use aya::programs::UProbe;

let program: &mut UProbe = bpf.program_mut("SSL_read").unwrap().try_into()?;
program.load()?;
program.attach(Some("SSL_read"), 0, "libssl", None)?;
```
```
Tokens:
Raw