FS.h interfaces often return either incorrect large values or zero when there's an underlying filesystem error

[ssilverman]

Many of the FileImpl and File functions return size_t, however it's very common for the underlying filesystem implementation to return a negative value as an error code. A great example is LittleFS. The implementation here drops all error codes, for example in the case of LFS_ERR_NOSPC (-28), the very-common "No space left on device" condition, possibly transforming them into very large positive values.

Another way of phrasing this problem: The return values for the unsigned-returning functions return incorrect (and very large) values when there's an underlying filesystem error.

(Old issue title: "FileImpl in FS.h can't propagate underlying filesystem errors because of unsigned return values; also incorrect return values for errors")

It's not possible to determine what the problem is just by using the base interfaces from FS.h.

It's non-trivial to fix this problem because libraries external to the core depend on the definitions here. LittleFS is a great example.

At least in the Stream and Print interfaces, there's a way to set and retrieve an associated read or write error code, even through, say, write() returns size_t.

There are four possible fixes that jump out straight away (only the first three work):

1. Change all unsigned return values to their signed equivalents, for example, ssize_t instead of size_t.
2. Change FileImpl to implement the Stream interface; that would provide the necessary error code retrieval mechanism.
3. Add some sort of "get last error" function that returns a ssize_t.
4. Update the FS.h-related documentation to advise to always cast return values to their signed counterparts. Note that this solution doesn't actually work with the current implementation (eg. see the LittleFS implementation in the link above) because negative values are often detected and then changed to zero.

In summary, the FS.h interfaces are not completely usable in a production system because it's not possible to detect underlying filesystem errors, and when there is an error, it appears as either a very large unsigned value or zero (because it's been changed to zero).