From e3da02a12a9eca8864f3986ebaf4df1a5e0b68d7 Mon Sep 17 00:00:00 2001 From: Nikolaus Rath Date: Tue, 3 Dec 2024 12:57:48 +0000 Subject: [PATCH] Document semantics of `add_entry` parameter to `readdir` callback. Fixes: #196. --- src/api/filesystem/async_io.rs | 8 ++++++-- src/api/filesystem/sync_io.rs | 9 +++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/src/api/filesystem/async_io.rs b/src/api/filesystem/async_io.rs index fdc846a4e..467526eec 100644 --- a/src/api/filesystem/async_io.rs +++ b/src/api/filesystem/async_io.rs @@ -618,7 +618,9 @@ pub trait AsyncFileSystem: FileSystem { /// the file system did not return a `Handle` from `opendir` then the contents of `handle` are /// undefined. /// - /// `size` indicates the maximum number of bytes that should be returned by this method. + /// `size` indicates the maximum number of bytes that should be returned by this method, + /// but can be ignored in practice. Instead, entries are returned by calling the + /// `add_entry` function until it returns zero (indicating that the buffer is full). /// /// If `offset` is non-zero then it corresponds to one of the `offset` values from a `DirEntry` /// that was previously returned by a call to `readdir` for the same handle. In this case the @@ -659,7 +661,9 @@ pub trait AsyncFileSystem: FileSystem { /// the file system did not return a `Handle` from `opendir` then the contents of `handle` are /// undefined. /// - /// `size` indicates the maximum number of bytes that should be returned by this method. + /// `size` indicates the maximum number of bytes that should be returned by this method, + /// but can be ignored in practice. Instead, entries are returned by calling the + /// `add_entry` function until it returns zero (indicating that the buffer is full). /// /// Unlike `readdir`, the lookup count for `Inode`s associated with the returned directory /// entries **IS** affected by this method (since it returns an `Entry` for each `DirEntry`). diff --git a/src/api/filesystem/sync_io.rs b/src/api/filesystem/sync_io.rs index c3b7df43c..1c1fd5cdd 100644 --- a/src/api/filesystem/sync_io.rs +++ b/src/api/filesystem/sync_io.rs @@ -634,7 +634,9 @@ pub trait FileSystem { /// the file system did not return a `Handle` from `opendir` then the contents of `handle` are /// undefined. /// - /// `size` indicates the maximum number of bytes that should be returned by this method. + /// `size` indicates the maximum number of bytes that should be returned by this method, + /// but can be ignored in practice. Instead, entries are returned by calling the + /// `add_entry` function until it returns zero (indicating that the buffer is full). /// /// If `offset` is non-zero then it corresponds to one of the `offset` values from a `DirEntry` /// that was previously returned by a call to `readdir` for the same handle. In this case the @@ -675,7 +677,10 @@ pub trait FileSystem { /// the file system did not return a `Handle` from `opendir` then the contents of `handle` are /// undefined. /// - /// `size` indicates the maximum number of bytes that should be returned by this method. + /// `size` indicates the maximum number of bytes that should be returned by this method, + /// but can be ignored in practice. Instead, entries are returned by calling the + /// `add_entry` function until it returns zero (indicating that the buffer is full). + /// /// /// Unlike `readdir`, the lookup count for `Inode`s associated with the returned directory /// entries **IS** affected by this method (since it returns an `Entry` for each `DirEntry`).