No documentation on variables such as "lfs_off_t"

[emielsteerneman]

Hello,

I am trying to figure out how to use this library, and I'm stuck on the meaning of certain variables, such as lfs_off_t. First, I searched throughout all the files, especially lfs.h, but there seems to be no documentation on the functions nor their arguments. I tried Google but no results. Next I asked ChatGPT, and it came up with the following answer.

Is this the correct definition for the variable lfs_off_t? What about others such as lfs_soff_t, struct lfs_gstate, struct lfs_mlist. Is this simply nomenclature borrowed from previous libraries? Where does one learn the meaning behind all these variables?

[geky]

Hi @emielsteerneman, thanks for creating an issue.

It's interesting to see ChatGPT's thoughts, I hadn't really realized it would even know what LittleFS is.

lfs_off_t and lfs_soff_t are declared here:

littlefs/lfs.h

Lines 40 to 45 in 6a53d76

	// Type definitions
	typedef uint32_t lfs_size_t;
	typedef uint32_t lfs_off_t;
	typedef int32_t lfs_ssize_t;
	typedef int32_t lfs_soff_t;

These are types that map to integers that can represent any offset in a file. In littlefs they are pretty much the same as lfs_size_t and lfs_ssize_t, but have a different name to make it a bit more clear internally when a variable is keeping track of a size or offset.

Like lfs_size_t and lfs_ssize_t, the s prefix indicates if the type is signed or not. This is a bit different from Linux/POSIX where off_t is implicitly signed.

In the user-facing API, lfs_off_t is mostly used for lfs_file_seek, which changes the current "file position" in an open file.

---

struct lfs_gstate and struct lfs_mlist are internal structures, if you're not modifying the internals of littlefs you likely don't need to know what these are. They only exist in lfs.h because they exist in lfs_t, which needs to be in lfs.h so the linker knows how big it is.

These names are mostly made up because some of them are rather littlefs-specific concepts.

• struct lfs_gstate - This struct holds the current "global state" of the filesystem. This is some small, distributed metadata used to synchronize cross-mdir operations.

  More info here: DESIGN.md#the-move-problem

• struct lfs_mlist - This is an internal linked-list used to keep track of any open mdirs in the filsystem. This includes any open files and directories.

• lfs_mdir_t - This struct contains the state of a fetched metadata-pair. Metadata-pairs are pairs of two metadata blocks that create mutable+atomic containers of metadata. All files/dirs in littlefs store their metadata in metadata-pairs.

  More info here: DESIGN.md#metadata-pairs

Hopefully this info helps.