---@meta

-- Generated from native/src/bindings/core/fs.cpp. Do not edit.

---@class FsLib
---@field MAX_READ_BYTES integer Largest portable whole-file or line read.
fs = {}
fs.MAX_READ_BYTES = 65536

---Whether a path exists.
---@param path string Absolute SD-card path; traversal components are rejected.
---@return boolean
function fs.exists(path) end

---Returns the size of a file in bytes.
---@param path string Absolute SD-card path.
---@return integer? size
---@return string? error Present when the path is missing or not a file.
function fs.fileSize(path) end

---Lists the directories in a directory.
---@param path string Absolute directory path.
---@return string[]? names Sorted names, excluding hidden entries.
---@return string? error
function fs.listDirs(path) end

---Lists the files in a directory.
---@param path string Absolute directory path.
---@return string[]? names Sorted names, excluding hidden entries.
---@return string? error
function fs.listFiles(path) end

---Creates a directory.
---@param path string Absolute directory path.
---@return true? ok
---@return string? error
function fs.mkdir(path) end

---Reads a whole file.
---@param path string Absolute file path.
---@param maxBytes integer Maximum bytes to allocate, up to fs.MAX_READ_BYTES; oversized files fail rather than truncate.
---@return string? content
---@return string? error
function fs.readFile(path, maxBytes) end

---Reads one line starting at a byte offset.
---@param path string Absolute file path.
---@param offset integer Zero-based byte offset; a mid-line offset advances to the next line.
---@param maxBytes integer Maximum line bytes to allocate, up to fs.MAX_READ_BYTES.
---@return string? line Nil at end of file or on failure.
---@return integer? nextOffset Byte offset of the following line.
---@return string? error Present when the file cannot be read or the line exceeds maxBytes.
function fs.readLineAt(path, offset, maxBytes) end

---Removes a file.
---@param path string Absolute file path. Firmware-protected roots cannot be removed.
---@return true? ok
---@return string? error
function fs.remove(path) end

---Removes a directory and everything below it.
---@param path string Absolute directory path. Firmware-protected roots cannot be removed.
---@return true? ok
---@return string? error
function fs.removeTree(path) end

---Renames a file or directory.
---@param source string Absolute source path.
---@param destination string Absolute destination path, which must not exist.
---@return true? ok
---@return string? error
function fs.rename(source, destination) end

---Atomically replaces the destination or leaves its previous contents intact.
---@param path string Absolute file path.
---@param content string
---@return true? ok
---@return string? error
function fs.writeFile(path, content) end