diff --git a/src/lib.rs b/src/lib.rs index 07162524..4885f387 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -183,7 +183,9 @@ impl KernelConfig { /// /// The kernel currently has a hard maximum value of 2. Anything higher won't work. /// - /// On success, returns the previous value. On error, returns the nearest value which will succeed. + /// On success, returns the previous value. + /// # Errors + /// If argument is too large, returns the nearest value which will succeed. #[cfg(feature = "abi-7-40")] pub fn set_max_stack_depth(&mut self, value: u32) -> Result { // https://lore.kernel.org/linux-fsdevel/CAOYeF9V_n93OEF_uf0Gwtd=+da0ReX8N2aaT6RfEJ9DPvs8O2w@mail.gmail.com/ @@ -202,7 +204,9 @@ impl KernelConfig { /// /// Must be a power of 10 nanoseconds. i.e. 1s, 0.1s, 0.01s, 1ms, 0.1ms...etc /// - /// On success returns the previous value. On error returns the nearest value which will succeed + /// On success returns the previous value. + /// # Errors + /// If the argument does not match any valid granularity, returns the nearest value which will succeed. #[cfg(feature = "abi-7-23")] pub fn set_time_granularity(&mut self, value: Duration) -> Result { if value.as_nanos() == 0 { @@ -226,7 +230,9 @@ impl KernelConfig { /// Set the maximum write size for a single request /// - /// On success returns the previous value. On error returns the nearest value which will succeed + /// On success returns the previous value. + /// # Errors + /// If the argument is too large, returns the nearest value which will succeed. pub fn set_max_write(&mut self, value: u32) -> Result { if value == 0 { return Err(1); @@ -241,7 +247,9 @@ impl KernelConfig { /// Set the maximum readahead size /// - /// On success returns the previous value. On error returns the nearest value which will succeed + /// On success returns the previous value. + /// # Errors + /// If the argument is too large, returns the nearest value which will succeed. pub fn set_max_readahead(&mut self, value: u32) -> Result { if value == 0 { return Err(1); @@ -256,7 +264,8 @@ impl KernelConfig { /// Add a set of capabilities. /// - /// On success returns Ok, else return bits of capabilities not supported when capabilities you provided are not all supported by kernel. + /// # Errors + /// When the argument includes capabilities not supported by the kernel, returns the bits of the capabilities not supported. pub fn add_capabilities(&mut self, capabilities_to_add: u64) -> Result<(), u64> { if capabilities_to_add & self.capabilities != capabilities_to_add { return Err(capabilities_to_add - (capabilities_to_add & self.capabilities)); @@ -267,7 +276,9 @@ impl KernelConfig { /// Set the maximum number of pending background requests. Such as readahead requests. /// - /// On success returns the previous value. On error returns the nearest value which will succeed + /// On success returns the previous value. + /// # Errors + /// If the argument is too small, returns the nearest value which will succeed. pub fn set_max_background(&mut self, value: u16) -> Result { if value == 0 { return Err(1); @@ -280,7 +291,9 @@ impl KernelConfig { /// Set the threshold of background requests at which the kernel will consider the filesystem /// request queue congested. (it may then switch to sleeping instead of spin-waiting, for example) /// - /// On success returns the previous value. On error returns the nearest value which will succeed + /// On success returns the previous value. + /// # Errors + /// If the argument is too small, returns the nearest value which will succeed. pub fn set_congestion_threshold(&mut self, value: u16) -> Result { if value == 0 { return Err(1); @@ -952,6 +965,9 @@ pub trait Filesystem { /// not return until the filesystem is unmounted. /// /// Note that you need to lead each option with a separate `"-o"` string. +/// # Errors +/// Returns an error if the options are incorrect, or if the fuse device can't be mounted, +/// and any final error when the session comes to an end. #[deprecated(note = "use mount2() instead")] pub fn mount>( filesystem: FS, @@ -966,6 +982,9 @@ pub fn mount>( /// not return until the filesystem is unmounted. /// /// NOTE: This will eventually replace `mount()`, once the API is stable +/// # Errors +/// Returns an error if the options are incorrect, or if the fuse device can't be mounted, +/// and any final error when the session comes to an end. pub fn mount2>( filesystem: FS, mountpoint: P, @@ -980,6 +999,8 @@ pub fn mount2>( /// and therefore returns immediately. The returned handle should be stored /// to reference the mounted filesystem. If it's dropped, the filesystem will /// be unmounted. +/// # Errors +/// Returns an error if the options are incorrect, or if the fuse device can't be mounted. #[deprecated(note = "use spawn_mount2() instead")] pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef>( filesystem: FS, @@ -1002,6 +1023,8 @@ pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef>( /// be unmounted. /// /// NOTE: This is the corresponding function to mount2. +/// # Errors +/// Returns an error if the options are incorrect, or if the fuse device can't be mounted. pub fn spawn_mount2<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef>( filesystem: FS, mountpoint: P, diff --git a/src/ll/reply.rs b/src/ll/reply.rs index 204fa34f..c7590f83 100644 --- a/src/ll/reply.rs +++ b/src/ll/reply.rs @@ -407,7 +407,7 @@ impl> DirEntry { } } -/// Used to respond to [ReadDirPlus] requests. +/// Data buffer used to respond to [`Readdir`] requests. #[derive(Debug)] pub struct DirEntList(EntListBuf); impl From for Response<'_> { @@ -471,7 +471,7 @@ impl> DirEntryPlus { } } -/// Used to respond to [ReadDir] requests. +/// Data buffer used to respond to [`ReaddirPlus`] requests. #[derive(Debug)] pub struct DirEntPlusList(EntListBuf); impl From for Response<'_> { diff --git a/src/notify.rs b/src/notify.rs index 95dc8033..e332cd36 100644 --- a/src/notify.rs +++ b/src/notify.rs @@ -30,6 +30,8 @@ impl PollHandle { } /// Notify the kernel that the associated file handle is ready to be polled. + /// # Errors + /// Returns an error if the kernel rejects the notification. pub fn notify(self) -> io::Result<()> { self.notifier.poll(self.handle) } @@ -57,12 +59,17 @@ impl Notifier { } /// Notify poll clients of I/O readiness + /// # Errors + /// Returns an error if the kernel rejects the notification. pub fn poll(&self, kh: u64) -> io::Result<()> { let notif = Notification::new_poll(kh); self.send(notify_code::FUSE_POLL, ¬if) } /// Invalidate the kernel cache for a given directory entry + /// # Errors + /// Returns an error if the notification data is too large. + /// Returns an error if the kernel rejects the notification. pub fn inval_entry(&self, parent: u64, name: &OsStr) -> io::Result<()> { let notif = Notification::new_inval_entry(parent, name).map_err(Self::too_big_err)?; self.send_inval(notify_code::FUSE_NOTIFY_INVAL_ENTRY, ¬if) @@ -70,12 +77,17 @@ impl Notifier { /// Invalidate the kernel cache for a given inode (metadata and /// data in the given range) + /// # Errors + /// Returns an error if the kernel rejects the notification. pub fn inval_inode(&self, ino: u64, offset: i64, len: i64) -> io::Result<()> { let notif = Notification::new_inval_inode(ino, offset, len); self.send_inval(notify_code::FUSE_NOTIFY_INVAL_INODE, ¬if) } /// Update the kernel's cached copy of a given inode's data + /// # Errors + /// Returns an error if the notification data is too large. + /// Returns an error if the kernel rejects the notification. pub fn store(&self, ino: u64, offset: u64, data: &[u8]) -> io::Result<()> { let notif = Notification::new_store(ino, offset, data).map_err(Self::too_big_err)?; // Not strictly an invalidate, but the inode we're operating @@ -85,6 +97,9 @@ impl Notifier { /// Invalidate the kernel cache for a given directory entry and inform /// inotify watchers of a file deletion. + /// # Errors + /// Returns an error if the notification data is too large. + /// Returns an error if the kernel rejects the notification. pub fn delete(&self, parent: u64, child: u64, name: &OsStr) -> io::Result<()> { let notif = Notification::new_delete(parent, child, name).map_err(Self::too_big_err)?; self.send_inval(notify_code::FUSE_NOTIFY_DELETE, ¬if) diff --git a/src/reply.rs b/src/reply.rs index f065d1ca..7e7ff8f1 100644 --- a/src/reply.rs +++ b/src/reply.rs @@ -276,6 +276,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. pub fn opened(self, fh: u64, flags: u32) { #[cfg(feature = "abi-7-40")] assert_eq!(flags & FOPEN_PASSTHROUGH, 0); @@ -326,7 +328,7 @@ impl Reply for ReplyWrite { } impl ReplyWrite { - /// Reply to a request with the given open result + /// Reply to a request with the number of bytes written pub fn written(self, size: u32) { self.reply.send_ll(&ll::Response::new_write(size)); } @@ -354,7 +356,7 @@ impl Reply for ReplyStatfs { } impl ReplyStatfs { - /// Reply to a request with the given open result + /// Reply to a statfs request with filesystem information #[allow(clippy::too_many_arguments)] pub fn statfs( self, @@ -395,7 +397,9 @@ impl Reply for ReplyCreate { } impl ReplyCreate { - /// Reply to a request with the given entry + /// Reply to a request with a newly created file entry and its newly open file handle + /// # Panics + /// When attempting to use kernel passthrough. Use `opened_passthrough()` instead. pub fn created(self, ttl: &Duration, attr: &FileAttr, generation: u64, fh: u64, flags: u32) { #[cfg(feature = "abi-7-40")] assert_eq!(flags & FOPEN_PASSTHROUGH, 0); @@ -432,7 +436,7 @@ impl Reply for ReplyLock { } impl ReplyLock { - /// Reply to a request with the given open result + /// Reply to a request with a file lock pub fn locked(self, start: u64, end: u64, typ: i32, pid: u32) { self.reply.send_ll(&ll::Response::new_lock(&ll::Lock { range: (start, end), @@ -464,7 +468,7 @@ impl Reply for ReplyBmap { } impl ReplyBmap { - /// Reply to a request with the given open result + /// Reply to a request with a bmap pub fn bmap(self, block: u64) { self.reply.send_ll(&ll::Response::new_bmap(block)); } @@ -492,7 +496,7 @@ impl Reply for ReplyIoctl { } impl ReplyIoctl { - /// Reply to a request with the given open result + /// Reply to a request with an ioctl pub fn ioctl(self, result: i32, data: &[u8]) { self.reply .send_ll(&ll::Response::new_ioctl(result, &[IoSlice::new(data)])); @@ -521,7 +525,7 @@ impl Reply for ReplyPoll { } impl ReplyPoll { - /// Reply to a request with the given poll result + /// Reply to a request with ready poll events pub fn poll(self, revents: u32) { self.reply.send_ll(&ll::Response::new_poll(revents)); } @@ -645,12 +649,12 @@ impl Reply for ReplyXattr { } impl ReplyXattr { - /// Reply to a request with the size of the xattr. + /// Reply to a request with the size of an extended attribute pub fn size(self, size: u32) { self.reply.send_ll(&ll::Response::new_xattr_size(size)); } - /// Reply to a request with the data in the xattr. + /// Reply to a request with the data of an extended attribute pub fn data(self, data: &[u8]) { self.reply.send_ll(&ll::Response::new_slice(data)); } diff --git a/src/session.rs b/src/session.rs index 467eb4c4..e1393a2d 100644 --- a/src/session.rs +++ b/src/session.rs @@ -75,6 +75,8 @@ impl AsFd for Session { impl Session { /// Create a new session by mounting the given filesystem to the given mountpoint + /// # Errors + /// Returns an error if the options are incorrect, or if the fuse device can't be mounted. pub fn new>( filesystem: FS, mountpoint: P, @@ -142,6 +144,8 @@ impl Session { /// calls into the filesystem. This read-dispatch-loop is non-concurrent to prevent /// having multiple buffers (which take up much memory), but the filesystem methods /// may run concurrent by spawning threads. + /// # Errors + /// Returns any final error when the session comes to an end. pub fn run(&mut self) -> io::Result<()> { // Buffer for receiving requests from the kernel. Only one is allocated and // it is reused immediately after dispatching to conserve memory and allocations. @@ -262,6 +266,8 @@ impl BackgroundSession { }) } /// Unmount the filesystem and join the background thread. + /// # Panics + /// Panics if the background thread can't be recovered (e.g., because it panicked). pub fn join(self) { let Self { guard,