Add ProgramHandle: owned, lifetime-independent handle for loaded BPF programs

  Mirrors MapHandle pattern — owns fd via OwnedFd, caches name/type/tag/id.
  Constructors: from_prog_id, from_pinned_path, TryFrom<&Program>.
  Implements AsFd, pin/unpin, TryFrom<&Self> for cloning.

  Closes #920

Author: cong-or

libbpf-rs/src/lib.rs

@@ -147,6 +147,7 @@ pub use crate::program::Output as ProgramOutput;
 pub use crate::program::PerfEventOpts;
 pub use crate::program::Program;
 pub use crate::program::ProgramAttachType;
+pub use crate::program::ProgramHandle;
 pub use crate::program::ProgramImpl;
 pub use crate::program::ProgramMut;
 pub use crate::program::ProgramType;

libbpf-rs/src/program.rs

@@ -6,6 +6,9 @@ use std::ffi::c_void;
 use std::ffi::CStr;
 use std::ffi::CString;
 use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::fmt::Debug;
+use std::fs::remove_file;
 use std::io::Read;
 use std::marker::PhantomData;
 use std::mem;
@@ -1730,6 +1733,127 @@ impl<T> AsRawLibbpf for ProgramImpl<'_, T> {
     }
 }
 
+/// An owned handle to a loaded BPF program.
+///
+/// Similar to [`MapHandle`][crate::MapHandle] for maps: owns the file descriptor
+/// and caches metadata, so it can outlive the [`Object`][crate::Object] it came from.
+#[derive(Debug)]
+pub struct ProgramHandle {
+    fd: OwnedFd,
+    name: OsString,
+    ty: ProgramType,
+    tag: [u8; 8],
+    id: u32,
+}
+
+impl ProgramHandle {
+    fn from_fd(fd: OwnedFd) -> Result<Self> {
+        let mut info = libbpf_sys::bpf_prog_info::default();
+        let mut len = size_of::<libbpf_sys::bpf_prog_info>() as u32;
+        let ret = unsafe {
+            libbpf_sys::bpf_obj_get_info_by_fd(
+                fd.as_raw_fd(),
+                (&mut info as *mut libbpf_sys::bpf_prog_info).cast::<c_void>(),
+                &mut len,
+            )
+        };
+        util::parse_ret(ret)?;
+
+        let name_cstr = util::c_char_slice_to_cstr(&info.name)
+            .ok_or_else(|| Error::with_invalid_data("program name not NUL-terminated"))?;
+        let name = OsStr::from_bytes(name_cstr.to_bytes()).to_os_string();
+
+        Ok(Self {
+            fd,
+            name,
+            ty: ProgramType::from(info.type_),
+            tag: info.tag,
+            id: info.id,
+        })
+    }
+
+    /// Open a loaded program by its kernel ID.
+    pub fn from_prog_id(id: u32) -> Result<Self> {
+        Self::from_fd(Program::fd_from_id(id)?)
+    }
+
+    /// Open a previously pinned program from its bpffs path.
+    pub fn from_pinned_path<P: AsRef<Path>>(path: P) -> Result<Self> {
+        let fd = Program::fd_from_pinned_path(path)?;
+        Self::from_fd(fd)
+    }
+
+    /// The program's name.
+    pub fn name(&self) -> &OsStr {
+        &self.name
+    }
+
+    /// The `ProgramType` of this handle.
+    pub fn prog_type(&self) -> ProgramType {
+        self.ty
+    }
+
+    /// The 8-byte tag (instruction hash) of the program.
+    pub fn tag(&self) -> [u8; 8] {
+        self.tag
+    }
+
+    /// The kernel ID of this program.
+    pub fn id(&self) -> u32 {
+        self.id
+    }
+
+    /// [Pin](https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#bpffs)
+    /// this program to bpffs.
+    pub fn pin<P: AsRef<Path>>(&self, path: P) -> Result<()> {
+        let path_c = util::path_to_cstring(path)?;
+        let ret = unsafe { libbpf_sys::bpf_obj_pin(self.fd.as_raw_fd(), path_c.as_ptr()) };
+        util::parse_ret(ret)
+    }
+
+    /// [Unpin](https://facebookmicrosites.github.io/bpf/blog/2018/08/31/object-lifetime.html#bpffs)
+    /// this program from bpffs.
+    pub fn unpin<P: AsRef<Path>>(&self, path: P) -> Result<()> {
+        remove_file(path).context("failed to remove pinned program")
+    }
+}
+
+impl AsFd for ProgramHandle {
+    #[inline]
+    fn as_fd(&self) -> BorrowedFd<'_> {
+        self.fd.as_fd()
+    }
+}
+
+impl<T: Debug> TryFrom<&ProgramImpl<'_, T>> for ProgramHandle {
+    type Error = Error;
+
+    fn try_from(prog: &ProgramImpl<'_, T>) -> Result<Self> {
+        let fd = prog
+            .as_fd()
+            .try_clone_to_owned()
+            .context("failed to duplicate program file descriptor")?;
+        Self::from_fd(fd)
+    }
+}
+
+impl TryFrom<&Self> for ProgramHandle {
+    type Error = Error;
+
+    fn try_from(other: &Self) -> Result<Self> {
+        Ok(Self {
+            fd: other
+                .as_fd()
+                .try_clone_to_owned()
+                .context("failed to duplicate program file descriptor")?,
+            name: other.name.clone(),
+            ty: other.ty,
+            tag: other.tag,
+            id: other.id,
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

libbpf-rs/tests/test.rs

@@ -59,6 +59,7 @@ use libbpf_rs::Object;
 use libbpf_rs::ObjectBuilder;
 use libbpf_rs::PerfEventOpts;
 use libbpf_rs::Program;
+use libbpf_rs::ProgramHandle;
 use libbpf_rs::ProgramInput;
 use libbpf_rs::ProgramType;
 use libbpf_rs::RawTracepointOpts;
@@ -3032,3 +3033,85 @@ fn test_prog_info_verified_insns() {
         info.verified_insns,
     );
 }
+
+#[tag(root)]
+#[test]
+fn test_program_handle_from_prog_id() {
+    let mut obj = get_test_object("runqslower.bpf.o");
+    let prog = get_prog_mut(&mut obj, "handle__sched_switch");
+    let prog_id = Program::id_from_fd(prog.as_fd()).expect("failed to get program id");
+
+    let handle = ProgramHandle::from_prog_id(prog_id).expect("failed to create handle from id");
+    assert_eq!(handle.name(), prog.name());
+    assert_eq!(handle.prog_type(), prog.prog_type());
+    assert_eq!(handle.id(), prog_id);
+}
+
+#[tag(root)]
+#[test]
+fn test_program_handle_from_pinned_path() {
+    let path = "/sys/fs/bpf/test_prog_handle_pinned";
+
+    let mut obj = get_test_object("runqslower.bpf.o");
+    let mut prog = get_prog_mut(&mut obj, "handle__sched_wakeup");
+    let prog_id = Program::id_from_fd(prog.as_fd()).expect("failed to get program id");
+    prog.pin(path).expect("failed to pin program");
+
+    defer! {
+        let _unused = fs::remove_file(path);
+    }
+
+    let handle =
+        ProgramHandle::from_pinned_path(path).expect("failed to create handle from pinned path");
+    assert_eq!(handle.id(), prog_id);
+    assert_eq!(handle.name(), "handle__sched_wakeup");
+}
+
+#[tag(root)]
+#[test]
+fn test_program_handle_try_from_program() {
+    let mut obj = get_test_object("runqslower.bpf.o");
+    let prog = get_prog_mut(&mut obj, "handle__sched_switch");
+
+    let handle = ProgramHandle::try_from(&prog).expect("failed to create handle from program");
+    assert_eq!(handle.name(), prog.name());
+    assert_eq!(handle.prog_type(), prog.prog_type());
+}
+
+/// Check that cloning a `ProgramHandle` via `TryFrom<&Self>` gives a distinct fd
+/// with the same metadata.
+#[tag(root)]
+#[test]
+fn test_program_handle_clone() {
+    let mut obj = get_test_object("runqslower.bpf.o");
+    let prog = get_prog_mut(&mut obj, "handle__sched_wakeup_new");
+    let handle1 = ProgramHandle::try_from(&prog).expect("failed to create handle");
+    let handle2 = ProgramHandle::try_from(&handle1).expect("failed to clone handle");
+
+    assert_eq!(handle1.name(), handle2.name());
+    assert_eq!(handle1.prog_type(), handle2.prog_type());
+    assert_eq!(handle1.tag(), handle2.tag());
+    assert_eq!(handle1.id(), handle2.id());
+    // The cloned handle must hold its own fd.
+    assert_ne!(handle1.as_fd().as_raw_fd(), handle2.as_fd().as_raw_fd());
+}
+
+#[tag(root)]
+#[test]
+fn test_program_handle_pin_unpin() {
+    let path = "/sys/fs/bpf/test_prog_handle_pin_unpin";
+
+    let mut obj = get_test_object("runqslower.bpf.o");
+    let prog = get_prog_mut(&mut obj, "handle__sched_switch");
+    let handle = ProgramHandle::try_from(&prog).expect("failed to create handle");
+
+    defer! {
+        let _unused = fs::remove_file(path);
+    }
+
+    handle.pin(path).expect("failed to pin program handle");
+    assert!(Path::new(path).exists());
+
+    handle.unpin(path).expect("failed to unpin program handle");
+    assert!(!Path::new(path).exists());
+}