Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions src/passthrough.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,13 @@ nix::ioctl_write_ptr!(

/// A reference to a previously opened fd intended to be used for passthrough
///
/// You can create these via `ReplyOpen::open_backing()` and send them via
/// `ReplyOpen::opened_passthrough()`.
/// You can create these via [`ReplyOpen::open_backing()`](crate::ReplyOpen::open_backing)
/// and send them via [`ReplyOpen::opened_passthrough()`](crate::ReplyOpen::opened_passthrough).
///
/// When working with backing IDs you need to ensure that they live "long enough". A good practice
/// is to create them in the `Filesystem::open()` impl, store them in the struct of your Filesystem
/// impl, then drop them in the `Filesystem::release()` impl. Dropping them immediately after
/// is to create them in the [`Filesystem::open()`](crate::Filesystem::open) impl,
/// store them in the struct of your Filesystem impl, then drop them in the
/// [`Filesystem::release()`](crate::Filesystem::release) impl. Dropping them immediately after
/// sending them in the `Filesystem::open()` impl can lead to the kernel returning EIO when userspace
/// attempts to access the file.
///
Expand Down
9 changes: 5 additions & 4 deletions src/reply.rs
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,8 @@ impl Reply for ReplyOpen {
impl ReplyOpen {
/// Reply to a request with the given open result
/// # Panics
/// When attempting to use kernel passthrough. Use `opened_passthrough()` instead.
/// When attempting to use kernel passthrough.
/// Use [`opened_passthrough()`](Self::opened_passthrough) instead.
pub fn opened(self, fh: u64, flags: u32) {
let flags = FopenFlags::from_bits_retain(flags);
assert!(!flags.contains(FopenFlags::FOPEN_PASSTHROUGH));
Expand All @@ -287,16 +288,16 @@ impl ReplyOpen {
}

/// Registers a fd for passthrough, returning a `BackingId`. Once you have the backing ID,
/// you can pass it as the 3rd parameter of `OpenReply::opened_passthrough()`. This is done in
/// you can pass it as the 3rd parameter of [`ReplyOpen::opened_passthrough()`]. This is done in
/// two separate steps because it may make sense to reuse backing IDs (to avoid having to
/// repeatedly reopen the underlying file or potentially keep thousands of fds open).
#[cfg(feature = "abi-7-40")]
pub fn open_backing(&self, fd: impl std::os::fd::AsFd) -> std::io::Result<BackingId> {
self.reply.sender.as_ref().unwrap().open_backing(fd.as_fd())
}

/// Reply to a request with an opened backing id. Call `ReplyOpen::open_backing()` to get one of
/// these.
/// Reply to a request with an opened backing id. Call [`ReplyOpen::open_backing()`]
/// to get one of these.
#[cfg(feature = "abi-7-40")]
pub fn opened_passthrough(self, fh: u64, flags: u32, backing_id: &BackingId) {
let flags = FopenFlags::from_bits_retain(flags) | FopenFlags::FOPEN_PASSTHROUGH;
Expand Down