Struct FExit 

pub struct FExit { /* private fields */ }

A program that can be attached to the exit point of (almost) any kernel function.

FExit programs are similar to kretprobes, but the difference is that fexit has practically zero overhead to call after the kernel function returns. Fexit programs can also be attached to other eBPF programs.

Minimum kernel version

The minimum kernel version required to use this feature is 5.5.

Test runs

TestRun support for FExit programs uses the kernel’s tracing BPF_PROG_TEST_RUN handler. That handler does not call the function passed to FExit::load. Instead, it runs the kernel’s fixed bpf_fentry_test* sequence, so the FExit program is executed only when it is attached to one of those built-in test targets. https://github.com/torvalds/linux/blob/v7.1-rc4/net/bpf/test_run.c#L702-L715

A successful test-run syscall means the kernel sequence completed. To check that an FExit program ran, record and verify an explicit side effect such as a map update. Ok(()) does not mean this FExit program ran.

Examples

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()?;

Implementations

impl FExit

pub const PROGRAM_TYPE: ProgramType = ProgramType::Tracing

The type of the program according to the kernel.

pub fn load(&mut self, fn_name: &str, btf: &Btf) -> Result<(), ProgramError>

Loads the program inside the kernel.

Loads the program so it’s executed when the kernel function fn_name is exited. The btf argument must contain the BTF info for the running kernel.

pub fn attach(&mut self) -> Result<FExitLinkId, ProgramError>

Attaches the program.

The returned value can be used to detach, see FExit::detach.

impl FExit

pub fn detach(&mut self, link_id: FExitLinkId) -> Result<(), ProgramError>

Detaches the program.

See Self::attach.

pub fn take_link( &mut self, link_id: FExitLinkId, ) -> Result<FExitLink, ProgramError>

Takes ownership of the link referenced by the provided link_id.

The caller takes the responsibility of managing the lifetime of the link. When the returned FExitLink is dropped, the link will be detached.

impl FExit

pub fn unload(&mut self) -> Result<(), ProgramError>

Unloads the program from the kernel.

Tracked links will be detached before unloading the program. Attachment mechanisms that do not create tracked links are not affected. Note that owned links obtained using take_link() will not be detached.

impl FExit

pub fn fd(&self) -> Result<&ProgramFd, ProgramError>

Returns the file descriptor of this Program.

impl FExit

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

Pins the program to a BPF filesystem.

When a BPF object is pinned to a BPF filesystem it will remain loaded after Aya has unloaded the program. To remove the program, the file on the BPF filesystem must be removed. Any directories in the the path provided should have been created by the caller.

pub fn unpin(&mut self) -> Result<(), Error>

Removes the pinned link from the filesystem.

impl FExit

pub fn from_pin<P: AsRef<Path>>(path: P) -> Result<Self, ProgramError>

Creates a program from a pinned entry on a bpffs.

Existing links will not be populated. To work with existing links you should use crate::programs::links::PinnedLink.

On drop, any managed links are detached and the program is unloaded. This will not result in the program being unloaded from the kernel if it is still pinned.

impl FExit

pub unsafe fn from_program_info( info: ProgramInfo, name: Cow<'static, str>, ) -> Result<Self, ProgramError>

Constructs an instance of a Self from a ProgramInfo.

This allows the caller to get a handle to an already loaded program from the kernel without having to load it again.

Errors

• If the program type reported by the kernel does not match Self::PROGRAM_TYPE.
• If the file descriptor of the program cannot be cloned.

Safety

The runtime type of this program, as used by the kernel, is overloaded. We assert the program type matches the runtime type but we’re unable to perform further checks. Therefore, the caller must ensure that the program type is correct or the behavior is undefined.

impl FExit

pub fn info(&self) -> Result<ProgramInfo, ProgramError>

Returns metadata information of this program.

Uses kernel v4.13 features.

Trait Implementations

impl Debug for FExit

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

Formats the value using the given formatter.

impl Drop for FExit

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl TestRun for FExit

type Opts<'a> = ()

The options type used to configure a single test invocation.

type Result = ()

The Result type for a single test invocation.

fn test_run(&self, _opts: Self::Opts<'_>) -> Result<Self::Result, ProgramError>

Runs the program with test input data and returns the result.

impl<'a> TryFrom<&'a Program> for &'a FExit

type Error = ProgramError

The type returned in the event of a conversion error.

fn try_from(program: &'a Program) -> Result<&'a FExit, ProgramError>

Performs the conversion.

impl<'a> TryFrom<&'a mut Program> for &'a mut FExit

type Error = ProgramError

The type returned in the event of a conversion error.

fn try_from(program: &'a mut Program) -> Result<&'a mut FExit, ProgramError>

Performs the conversion.