From 4016fed5815434202aeca74359db146417d78a1b Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Wed, 26 Aug 2026 22:50:55 +0200
Subject: kapi/fs: introduce read_directory API

---
 kapi/kapi/filesystem.hpp                  | 12 ++++++++++++
 kapi/kapi/filesystem/directory_cursor.hpp | 22 ++++++++++++++++++++++
 kapi/kapi/filesystem/directory_entry.hpp  | 24 ++++++++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 kapi/kapi/filesystem/directory_cursor.hpp
 create mode 100644 kapi/kapi/filesystem/directory_entry.hpp

(limited to 'kapi')

diff --git a/kapi/kapi/filesystem.hpp b/kapi/kapi/filesystem.hpp
index 6a0cd6c2..9da18c11 100644
--- a/kapi/kapi/filesystem.hpp
+++ b/kapi/kapi/filesystem.hpp
@@ -5,6 +5,8 @@
 #include <kapi/filesystem/block_special_file.hpp>      // IWYU pragma: export
 #include <kapi/filesystem/character_special_file.hpp>  // IWYU pragma: export
 #include <kapi/filesystem/device_number.hpp>           // IWYU pragma: export
+#include <kapi/filesystem/directory_cursor.hpp>        // IWYU pragma: export
+#include <kapi/filesystem/directory_entry.hpp>         // IWYU pragma: export
 #include <kapi/filesystem/file_status.hpp>             // IWYU pragma: export
 #include <kapi/filesystem/file_type.hpp>               // IWYU pragma: export
 #include <kapi/filesystem/seek.hpp>                    // IWYU pragma: export
@@ -16,6 +18,7 @@
 #include <cstddef>
 #include <span>
 #include <string_view>
+#include <utility>
 
 //! The interface for filesystem operations in the kernel.
 //!
@@ -104,6 +107,15 @@ namespace kapi::filesystem
   //! @return Nothing on success, an error on failure
   auto create_device_node(std::string_view path, file_type type, device_number number) -> kstd::result<void>;
 
+  //! List the contents of a directory.
+  //!
+  //! @param file_descriptor A file descriptor pointing to an open directory.
+  //! @param position The starting position of the listing.
+  //! @param buffer A buffer to write the directory entries into.
+  //! @return The number of entries read and the next read position on success, an error otherwise.
+  auto read_directory(std::size_t file_descriptor, directory_cursor position, std::span<directory_entry> buffer)
+      -> kstd::result<std::pair<std::size_t, directory_cursor>>;
+
   //! @}
 }  // namespace kapi::filesystem
 
diff --git a/kapi/kapi/filesystem/directory_cursor.hpp b/kapi/kapi/filesystem/directory_cursor.hpp
new file mode 100644
index 00000000..1ebddfcd
--- /dev/null
+++ b/kapi/kapi/filesystem/directory_cursor.hpp
@@ -0,0 +1,22 @@
+#ifndef TEACHOS_KAPI_FILESYSTEM_DIRECTORY_CURSOR_HPP
+#define TEACHOS_KAPI_FILESYSTEM_DIRECTORY_CURSOR_HPP
+
+// IWYU pragma: private, include <kapi/filesystem.hpp>
+
+#include <compare>
+#include <cstdint>
+
+namespace kapi::filesystem
+{
+
+  struct directory_cursor
+  {
+    constexpr auto friend operator<=>(directory_cursor const &, directory_cursor const &) noexcept
+        -> std::strong_ordering = default;
+
+    std::uint64_t value;
+  };
+
+}  // namespace kapi::filesystem
+
+#endif
diff --git a/kapi/kapi/filesystem/directory_entry.hpp b/kapi/kapi/filesystem/directory_entry.hpp
new file mode 100644
index 00000000..e881e415
--- /dev/null
+++ b/kapi/kapi/filesystem/directory_entry.hpp
@@ -0,0 +1,24 @@
+#ifndef TEACHOS_KAPI_FILESYSTEM_DIRECTORY_ENTRY_HPP
+#define TEACHOS_KAPI_FILESYSTEM_DIRECTORY_ENTRY_HPP
+
+// IWYU pragma: private, include <kapi/filesystem.hpp>
+
+#include <kapi/filesystem/file_type.hpp>
+
+#include <kstd/string.hpp>
+
+#include <cstdint>
+
+namespace kapi::filesystem
+{
+
+  struct directory_entry
+  {
+    std::uint64_t inode_number{};
+    file_type type{};
+    kstd::string name{};
+  };
+
+}  // namespace kapi::filesystem
+
+#endif
-- 
cgit v1.2.3