File System¶

This document describes the API and usage of the FileSystem library, which provides a set of functions and structures for managing files and directories on a LittleFS-based filesystem. The library includes utilities for mounting, formatting, reading, writing, and managing files and directories, as well as querying filesystem information.

It uses the namespace FS.

Functions¶

Filesystem Operations¶

format()
Formats the filesystem, erasing all data and preparing it for use.
Returns: 0 on success, or a negative error code on failure.
clear_dir(const char *path)
Clears all files and subdirectories in the specified directory.
Returns: 0 on success, or a negative error code on failure.
remove_file(const char *path)
Removes the specified file from the filesystem.
Returns: 0 on success, or a negative error code on failure.
info()
Prints information about the filesystem, including its status and available space.
flash_erase(unsigned int id, bool wipe_flash = false)
Erases the flash storage for the specified partition ID. Optionally wipes the entire flash storage.
Returns: 0 on success, or a negative error code on failure.
flash_erase(bool wipe_flash = false)
Erases the flash storage. Optionally wipes the entire flash storage.
Returns: 0 on success, or a negative error code on failure.

Mounting and Unmounting¶

mount(fs_mount_t *mp, bool initial = true, bool wipe_flash = false)
Mounts the filesystem at the specified mount point. Optionally wipes the flash storage before mounting.
Returns: 0 on success, or a negative error code on failure.
mount(bool initial = true, bool wipe_flash = false)
Mounts the filesystem. Optionally wipes the flash storage before mounting.
Returns: 0 on success, or a negative error code on failure.
unmount()
Unmounts the filesystem, making it no longer accessible.
Returns: 0 on success, or a negative error code on failure.

Directory and File Listing¶

lsdir(const char *path = "")
Prints the contents of the specified directory path.
Returns: 0 on success, or a negative error code on failure.

Entry Information¶

getEntryInfo(FS::FSEntry entry_info, const char path, int entry_index = -1)
Gets metadata of the specified directory entry (file or directory).

File Operations¶

increase_file_int(const char *fname)
Reads an integer value from the specified file, increments it, and writes the updated value back.
Returns: The read (positive) value, or a negative error code on failure.
load(const char fname, void buf, size_t buf_size, int32_t read_size = -1, uint32_t read_offset = 0)
Reads data from the specified file into the provided buffer.
Returns: The number of bytes read, or a negative error code on failure.
save(const char fname, const void buf, size_t buf_size, int32_t write_size = -1, uint32_t write_offset = 0)
Writes the contents of the provided buffer to the specified file.
Returns: The number of bytes written, or a negative error code on failure.

Structures¶

FSEntry¶

Represents a filesystem entry (file or directory) with the following fields:

entity_base_name: Name of the entry.
entry_index: Index of the entry in the directory listing.
size: Size of the entry in bytes.
unix_timestamp_of_last_modification: Last modification time in Unix timestamp format.
is_file_not_directory: true if the entry is a file, false if it is a directory.
is_link: true if the entry is a symbolic link.
is_readable: true if the entry is readable.
is_writeable: true if the entry is writable.

/**
 * @brief Prepend the mount point to the given path.
 *
 * This function modifies the full_path variable by the provided path and prepends the filesystem's
 * mount point.
 *
 * @param path The path to modify.
 */
int prepend_mount_point(const char *path);

/**
 * @brief Formats the filesystem.
 *
 * This function formats the filesystem, erasing all data and preparing it for use.
 *
 * @return 0 on success, or a negative error code on failure.
 */
int format();

/**
 * @brief Clears the given directory.
 *
 * This function clears all files and subdirectories in the specified directory.
 *
 * @param path The path of the directory to clear.
 * @return 0 on success, or a negative error code on failure.
 */
int clear_dir(const char *path);

/**
 * @brief Removes a file from the filesystem.
 *
 * This function removes the specified file from the filesystem.
 *
 * @param path The path of the file to remove, e.g. file.ending
 * @return 0 on success, or a negative error code on failure.
 */
int remove_file(const char *path);

/**
 * @brief Displays information about the filesystem.
 *
 * This function prints information about the filesystem, including its status
 * and available space.
 */
void info();

/**
 * @brief Erases the flash storage.
 *
 * This function erases the flash storage for the specified partition ID. Optionally,
 * it can wipe the entire flash storage.
 *
 * @param id The partition ID to erase.
 * @param wipe_flash If true, the entire flash storage will be wiped.
 * @return 0 on success, or a negative error code on failure.
 */
int flash_erase(unsigned int id, bool wipe_flash = false);
int flash_erase(bool wipe_flash = false);

/**
 * @brief Mounts the filesystem.
 *
 * This function mounts the filesystem at the specified mount point. Optionally,
 * it can wipe the flash storage before mounting.
 *
 * @param mp Pointer to the filesystem mount structure.
 * @param initial If true, the filesystem is formatted if mount fails (e.g. on first boot).
 * @param wipe_flash If true, the flash storage will be wiped before mounting.
 * @return 0 on success, or a negative error code on failure.
 */
int mount(fs_mount_t *mp, bool initial = true, bool wipe_flash = false);
int mount(bool initial = true, bool wipe_flash = false);

/**
 * @brief Unmounts the filesystem.
 *
 * This function unmounts the filesystem, making it no longer accessible.
 *
 * @return 0 on success, or a negative error code on failure.
 */
int unmount();

/**
 * @brief Lists (print) the contents of a directory.
 *
 * This function prints the contents of the specified directory path.
 *
 * @param path The path of the directory to list.
 * @return 0 on success, or a negative error code on failure.
 */
int lsdir(const char *path = "");

struct FSEntry {
 char *entity_base_name;
 int32_t entry_index{-1}; // Index of the entry in the directory listing.
 uint64_t size{0};        // Size of the entry in bytes.
 // Last modification time in Unix timestamp format.
 uint64_t unix_timestamp_of_last_modification{0};
 // True if the entry is a file, false if it is a directory.
 bool is_file_not_directory{false};
 bool is_link{false};     // True if the entry is a symbolic link.
 bool is_readable{true};  // True if the entry is readable.
 bool is_writeable{true}; // True if the entry is writable.
};

/**
 * @brief Gets Information of a entry (file/dir).
 *
 * This function gets the metadata of the specified directory path.
 *
 * @param path The path of the directory to list.
 */
int getEntryInfo(FS::FSEntry *entry_info, const char *path, int entry_index = -1);

/**
 * @brief Increases an integer value stored in a file.
 *
 * This function reads an integer value from the specified file, increments it,
 * and writes the updated value back to the file.
 *
 * @param fname The name of the file containing the integer value.
 * @return read (positive) value, or a negative error code on failure.
 */
int increase_file_int(const char *fname);

/**
 * @brief Loads data from a file into a buffer.
 *
 * This function reads data from the specified file into the provided buffer.
 *
 * @param fname The name of the file to read from.
 * @param buf Pointer to the buffer where data will be loaded.
 * @param buf_size Size of the buffer in bytes.
 * @param read_size The number of bytes to read from the file. If -1, reads the entire file (until
 * buf_size is reached).
 * @param read_offset The offset in the file from which to start reading.
 * @return The number of bytes read, or a negative error code on failure.
 */
int load(const char *fname, void *buf, size_t buf_size, int32_t read_size = -1,
  uint32_t read_offset = 0);

/**
 * @brief Saves data from a buffer to a file.
 *
 * This function writes the contents of the provided buffer to the specified file.
 *
 * @param fname The name of the file to write to.
 * @param buf Pointer to the buffer containing data to save.
 * @param buf_size Size of the buffer in bytes.
 * @param write_size The number of bytes to write to the file. If -1, writes the entire buffer
 * (buf_size).
 * @param write_offset The offset in the file where writing should start.
 * @return The number of bytes written, or a negative error code on failure.
 */
int save(const char *fname, const void *buf, size_t buf_size, int32_t write_size = -1,
  uint32_t write_offset = 0);