pub struct Iter { /* private fields */ }Expand description
A BPF iterator which allows to dump data from the kernel-space into the user-space.
It can be seen as an alternative to /proc filesystem as it offers more
flexibility about what information should be retrieved and how it should be
formatted.
§Minimum kernel version
The minimum kernel version required to use this feature is 5.8.
§Example
use std::io::{BufRead, BufReader};
use aya::{programs::{Iter, ProgramError}, BtfError, Btf, Ebpf};
let btf = Btf::from_sys_fs()?;
let program: &mut Iter = ebpf.program_mut("iter_prog").unwrap().try_into()?;
program.load("task", &btf)?;
let link_id = program.attach()?;
let link = program.take_link(link_id)?;
let file = link.into_file()?;
let reader = BufReader::new(file);
let mut lines = reader.lines();
for line in lines {
let line = line?;
println!("{line}");
}Implementations§
Source§impl Iter
impl Iter
Sourcepub const PROGRAM_TYPE: ProgramType = ProgramType::Tracing
pub const PROGRAM_TYPE: ProgramType = ProgramType::Tracing
The type of the program according to the kernel.
Sourcepub fn load(&mut self, iter_type: &str, btf: &Btf) -> Result<(), ProgramError>
pub fn load(&mut self, iter_type: &str, btf: &Btf) -> Result<(), ProgramError>
Loads the program inside the kernel.
Sourcepub fn attach(&mut self) -> Result<IterLinkId, ProgramError>
pub fn attach(&mut self) -> Result<IterLinkId, ProgramError>
Attaches the program.
The returned value can be used to detach, see Self::detach.
Source§impl Iter
impl Iter
Sourcepub fn detach(&mut self, link_id: IterLinkId) -> Result<(), ProgramError>
pub fn detach(&mut self, link_id: IterLinkId) -> Result<(), ProgramError>
Detaches the program.
See Self::attach.
Sourcepub fn take_link(
&mut self,
link_id: IterLinkId,
) -> Result<IterLink, ProgramError>
pub fn take_link( &mut self, link_id: IterLinkId, ) -> Result<IterLink, 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
IterLink
is dropped, the link will be detached.
Source§impl Iter
impl Iter
Sourcepub fn unload(&mut self) -> Result<(), ProgramError>
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.
Source§impl Iter
impl Iter
Sourcepub fn fd(&self) -> Result<&ProgramFd, ProgramError>
pub fn fd(&self) -> Result<&ProgramFd, ProgramError>
Returns the file descriptor of this Program.
Source§impl Iter
impl Iter
Sourcepub fn pin<P: AsRef<Path>>(&mut self, path: P) -> Result<(), PinError>
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.
Source§impl Iter
impl Iter
Sourcepub fn from_pin<P: AsRef<Path>>(path: P) -> Result<Self, ProgramError>
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.
Source§impl Iter
impl Iter
Sourcepub fn from_program_info(
info: ProgramInfo,
name: Cow<'static, str>,
) -> Result<Self, ProgramError>
pub 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.
Source§impl Iter
impl Iter
Sourcepub fn info(&self) -> Result<ProgramInfo, ProgramError>
pub fn info(&self) -> Result<ProgramInfo, ProgramError>
Returns metadata information of this program.
Uses kernel v4.13 features.