diff options
| -rw-r--r-- | kapi/kapi/filesystem.hpp | 107 |
1 files changed, 48 insertions, 59 deletions
diff --git a/kapi/kapi/filesystem.hpp b/kapi/kapi/filesystem.hpp index 316e5407..0f092d29 100644 --- a/kapi/kapi/filesystem.hpp +++ b/kapi/kapi/filesystem.hpp @@ -9,83 +9,72 @@ #include <span> #include <string_view> +//! The interface for filesystem operations in the kernel. +//! +//! It includes functions for mounting and unmounting filesystems, as well as basic file operations such as opening, +//! closing, reading from, and writing to files. The actual implementation of these functions is in the kernel's +//! filesystem subsystem, which will handle the specifics of different filesystem types and their interactions with the +//! underlying storage devices. namespace kapi::filesystem { - /** - @brief The kapi::filesystem namespace provides the interface for filesystem operations in the kernel. It includes - functions for mounting and unmounting filesystems, as well as basic file operations such as opening, closing, reading - from, and writing to files. The actual implementation of these functions is in the kernel's filesystem subsystem, - which will handle the specifics of different filesystem types and their interactions with the underlying storage - devices. - */ + //! @addtogroup kapi-filesystem-kernel-defined + //! @{ - /** - @brief Mounts a filesystem from the specified @p source at the specified @p target path. - @param source The source device or filesystem to mount. - @param target The target mount point. - @return Nothing on success, an error code otherwise. - @qualifier kernel-defined - */ + //! Mount a filesystem at the specified source path onto the specified target path. + //! + //! @param source The source device or filesystem to mount. + //! @param target The target mount point. + //! @return Nothing on success, an error code otherwise. auto mount(std::string_view source, std::string_view target) -> std::expected<void, kstd::error_code>; - /** - @brief Unmounts a filesystem from the specified @p target path. - @param target The target mount point to unmount. - @return Nothing on success, an error code otherwise. - @qualifier kernel-defined - */ + //! Unmount a filesystem from the specified target path. + //! + //! @param target The target mount point to unmount. + //! @return Nothing on success, an error code otherwise. auto umount(std::string_view target) -> std::expected<void, kstd::error_code>; - /** - @brief Opens a file at the specified @p path. - @param path The path to the file to open. - @return A file descriptor on success, an error code otherwise. - @qualifier kernel-defined - */ + //! Open a file at the specified path. + //! + //! @param path The path to the file to open. + //! @return A file descriptor on success, an error code otherwise. auto open(std::string_view path) -> std::expected<std::size_t, kstd::error_code>; - /** - @brief Closes a @p file_descriptor. - @param file_descriptor The file descriptor to close. - @return Nothing on success, an error code otherwise . - @qualifier kernel-defined - */ + //! Close a file descriptor. + //! + //! @param file_descriptor The file descriptor to close. + //! @return Nothing on success, an error code otherwise . auto close(size_t file_descriptor) -> std::expected<void, kstd::error_code>; - /** - @brief Reads @p size bytes into @p buffer from a @p file_descriptor. - @param file_descriptor The file descriptor to read from. - @param buffer The buffer to store the read data. - @return The number of bytes read on success, an error code otherwise. - @qualifier kernel-defined - */ + //! Read bytes from a file into a given buffer. + //! + //! @param file_descriptor The file descriptor to read from. + //! @param buffer The buffer to store the read data. + //! @return The number of bytes read on success, an error code otherwise. auto read(size_t file_descriptor, std::span<std::byte> buffer) -> std::expected<std::size_t, kstd::error_code>; - /** - @brief Writes @p size bytes from @p buffer to a @p file_descriptor. - @param file_descriptor The file descriptor to write to. - @param buffer The buffer containing the data to write. - @return The number of bytes written on success, an error code otherwise. - @qualifier kernel-defined - */ + //! Write bytes from a given buffer to a file descriptor. + //! + //! @param file_descriptor The file descriptor to write to. + //! @param buffer The buffer containing the data to write. + //! @return The number of bytes written on success, an error code otherwise. auto write(size_t file_descriptor, std::span<std::byte const> buffer) -> std::expected<std::size_t, kstd::error_code>; - /** - @brief Creates a new directory at the specified @p path. - @param path The path where the new directory should be created. - @return 0 on success, -1 on failure. - @qualifier kernel-defined - */ + //! Create a new directory at the specified path. + //! + //! @param path The path where the new directory should be created. + //! @return Nothing on success, an error on failure. auto mkdir(std::string_view path) -> kstd::result<void>; - /** - @brief Creates a new file at the specified @p path. - @param path The path where the new file should be created. - @return 0 on success, -1 on failure. - @qualifier kernel-defined - */ - // TODO remove again after the open method supports an optional create flag + //! Create a new file at the specified path. + //! + //! @deprecated this function is deprecated and slated for removal once kapi::filesystem::open supports the create + //! flag. + //! + //! @param path The path where the new file should be created. + //! @return Nothing on success, an error on failure. auto create(std::string_view path) -> kstd::result<void>; + + //! @} } // namespace kapi::filesystem #endif // TEACHOS_KAPI_FILESYSTEM_HPP
\ No newline at end of file |