sys/vfs_util: add VFS helper functions

[benpicco]

Contribution description

It is often quite handy to have a small file to store a flag or an instruction or similar.
Instead of writing the same sequence of commands each time, provide a small helper function so the job can be done with a single line of code.

Testing procedure

Issues/PRs references

split off #17379

[chrysn]

While this is the right place from the module point of view, it's hard to discover. Maybe add a pointer to the vfs_read doc saying that "To read a complete file into a buffer, see also @ref vfs_file_to_buffer", or merely a "@see vfs_file_to_buffer".

[chrysn]

If this assurance is made toward the user, do we need to check that no other cause of error produces -ENOSPC? (It might be easier to just consider that a regular error with no guarantees -- also because that'd allow the implementation to instead stat the file after opening and return early without actually reading, if anyone wants to optimize that later.)

[benpicco]

I think no fs will generate this error in the read path, but I could add

if (res == -ENOSPC) {
    res = -ENOMEM;
}

[chrysn]

Documenting at the file system API that ENOSP must not be returned by read functions would also have worked, but this is the more robust way.

[chrysn]

I've added two fixes (build failed on native for lack of error include; copy/paste in docs) and the cross reference from the read/write functions; with that I think it's done; please review changes when you rebase.

Application with which I tested:

diff --git a/examples/filesystem/Makefile b/examples/filesystem/Makefile
index 11cd22c096..0f5f91ec06 100644
--- a/examples/filesystem/Makefile
+++ b/examples/filesystem/Makefile
@@ -30,6 +30,7 @@ USEMODULE += mtd
 
 # Use VFS
 USEMODULE += vfs
+USEMODULE += vfs_util
 
 # Use a file system
 # USEMODULE += littlefs
diff --git a/examples/filesystem/main.c b/examples/filesystem/main.c
index bedfe131c8..95ca4408fd 100644
--- a/examples/filesystem/main.c
+++ b/examples/filesystem/main.c
@@ -22,6 +22,7 @@
 #include <string.h>
 #include <unistd.h>
 #include <fcntl.h>
+#include <vfs_util.h>
 
 #include "shell.h"
 #include "board.h" /* MTD_0 is defined in board.h */
@@ -239,7 +240,17 @@ static int _cat(int argc, char **argv)
     }
     /* With newlib or picolibc, low-level syscalls are plugged to RIOT vfs
      * on native, open/read/write/close/... are plugged to RIOT vfs */
-#if defined(MODULE_NEWLIB) || defined(MODULE_PICOLIBC)
+#if 1
+    uint8_t buf[100];
+    int size = vfs_file_to_buffer(argv[1], buf, sizeof(buf));
+    if (size < 0) {
+        printf("file %s does not exist\n", argv[1]);
+        return 1;
+    }
+    for (int i = 0; i < size; ++i) {
+        printf("%02x ", buf[i]);
+    }
+#elif defined(MODULE_NEWLIB) || defined(MODULE_PICOLIBC)
     FILE *f = fopen(argv[1], "r");
     if (f == NULL) {
         printf("file %s does not exist\n", argv[1]);
@@ -273,7 +284,12 @@ static int _tee(int argc, char **argv)
         return 1;
     }
 
-#if defined(MODULE_NEWLIB) || defined(MODULE_PICOLIBC)
+#if 1
+    if (!vfs_file_from_buffer(argv[1], argv[2], strlen(argv[2]))) {
+        printf("error while trying to create %s\n", argv[1]);
+        return 1;
+    }
+#elif defined(MODULE_NEWLIB) || defined(MODULE_PICOLIBC)
     FILE *f = fopen(argv[1], "w+");
     if (f == NULL) {
         printf("error while trying to create %s\n", argv[1]);

[benpicco]

Thank you!