From 652c7a0e49d1caa3660dd80126f1197ebd3786da Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Sun, 23 Aug 2026 19:20:21 +0200
Subject: kernel/fs: introduce base read_directory API

---
 .../kernel/filesystem/directory_listing_cursor.hpp | 23 ++++++++++++++++++++++
 .../kernel/filesystem/directory_listing_entry.hpp  | 23 ++++++++++++++++++++++
 kernel/kernel/filesystem/inode.cpp                 | 12 +++++++++++
 kernel/kernel/filesystem/inode.hpp                 | 13 ++++++++++++
 4 files changed, 71 insertions(+)
 create mode 100644 kernel/kernel/filesystem/directory_listing_cursor.hpp
 create mode 100644 kernel/kernel/filesystem/directory_listing_entry.hpp

diff --git a/kernel/kernel/filesystem/directory_listing_cursor.hpp b/kernel/kernel/filesystem/directory_listing_cursor.hpp
new file mode 100644
index 00000000..5eb36c7a
--- /dev/null
+++ b/kernel/kernel/filesystem/directory_listing_cursor.hpp
@@ -0,0 +1,23 @@
+#ifndef TEACHOS_KERNEL_FILESYSTEM_DIRECTORY_LISTING_CURSOR_HPP
+#define TEACHOS_KERNEL_FILESYSTEM_DIRECTORY_LISTING_CURSOR_HPP
+
+#include <compare>
+#include <cstdint>
+
+namespace kernel::filesystem
+{
+
+  //! A cursor used to keep track of positions in directory listings.
+  struct directory_listing_cursor
+  {
+    constexpr auto friend operator<=>(directory_listing_cursor const &, directory_listing_cursor const &) noexcept
+        -> std::strong_ordering = default;
+    constexpr auto friend operator==(directory_listing_cursor const &, directory_listing_cursor const &) noexcept
+        -> bool = default;
+
+    std::uint64_t value;
+  };
+
+};  // namespace kernel::filesystem
+
+#endif
\ No newline at end of file
diff --git a/kernel/kernel/filesystem/directory_listing_entry.hpp b/kernel/kernel/filesystem/directory_listing_entry.hpp
new file mode 100644
index 00000000..f3dcf367
--- /dev/null
+++ b/kernel/kernel/filesystem/directory_listing_entry.hpp
@@ -0,0 +1,23 @@
+#ifndef TEACHOS_KERNEL_FILESYSTEM_DIRECTORY_LISTING_ENTRY_HPP
+#define TEACHOS_KERNEL_FILESYSTEM_DIRECTORY_LISTING_ENTRY_HPP
+
+#include <kapi/filesystem.hpp>
+
+#include <kstd/string.hpp>
+
+#include <cstdint>
+
+namespace kernel::filesystem
+{
+
+  //! An entry in a directory listing.
+  struct directory_listing_entry
+  {
+    kstd::string name;
+    kapi::filesystem::file_type type;
+    std::uint64_t inode_number;
+  };
+
+};  // namespace kernel::filesystem
+
+#endif
\ No newline at end of file
diff --git a/kernel/kernel/filesystem/inode.cpp b/kernel/kernel/filesystem/inode.cpp
index 26f523c6..7b290479 100644
--- a/kernel/kernel/filesystem/inode.cpp
+++ b/kernel/kernel/filesystem/inode.cpp
@@ -1,11 +1,17 @@
 #include <kernel/filesystem/inode.hpp>
 
+#include <kernel/filesystem/directory_listing_cursor.hpp>
+#include <kernel/filesystem/directory_listing_entry.hpp>
+#include <kernel/filesystem/error.hpp>
+
 #include <kapi/filesystem.hpp>
 
 #include <kstd/memory.hpp>
 #include <kstd/result.hpp>
 
+#include <cstddef>
 #include <optional>
+#include <span>
 #include <utility>
 
 namespace kernel::filesystem
@@ -78,6 +84,12 @@ namespace kernel::filesystem
     return std::nullopt;
   }
 
+  auto inode::read_directory(directory_listing_cursor, std::span<directory_listing_entry>) const
+      -> kstd::result<std::pair<std::size_t, directory_listing_cursor>>
+  {
+    return kstd::failure(vfs_errc::not_a_directory);
+  }
+
   auto inode::owning_mount() const noexcept -> kstd::weak_ptr<mount>
   {
     return m_owning_mount;
diff --git a/kernel/kernel/filesystem/inode.hpp b/kernel/kernel/filesystem/inode.hpp
index 677c5155..e7de9276 100644
--- a/kernel/kernel/filesystem/inode.hpp
+++ b/kernel/kernel/filesystem/inode.hpp
@@ -1,6 +1,9 @@
 #ifndef TEACHOS_KERNEL_FILESYSTEM_INODE_HPP
 #define TEACHOS_KERNEL_FILESYSTEM_INODE_HPP
 
+#include <kernel/filesystem/directory_listing_cursor.hpp>
+#include <kernel/filesystem/directory_listing_entry.hpp>
+
 #include <kapi/filesystem.hpp>
 
 #include <kstd/memory.hpp>
@@ -10,6 +13,7 @@
 #include <cstddef>
 #include <optional>
 #include <span>
+#include <utility>
 
 namespace kernel::filesystem
 {
@@ -104,6 +108,15 @@ namespace kernel::filesystem
     //! @return a device number if this inode refers to a device, an empty optional otherwise.
     [[nodiscard]] virtual auto raw_device() const -> std::optional<kapi::filesystem::device_number>;
 
+    //! List the contents of a directory.
+    //!
+    //! @param position The current directory listing position.
+    //! @param entries An output span to store directory entries.
+    //! @return A pair of the number or read entries and the next listing position on success, an error otherwise.
+    [[nodiscard]] virtual auto read_directory(directory_listing_cursor position,
+                                              std::span<directory_listing_entry> entries) const
+        -> kstd::result<std::pair<std::size_t, directory_listing_cursor>>;
+
     //! @}
 
     //! @name Mount Resolution
-- 
cgit v1.2.3