File system API reference

Author: igrr

hardware/esp8266com/esp8266/doc/reference.md

@@ -103,6 +103,145 @@ const char HTTP[] PROGMEM = "http:";
 }
 ```
 
+## File system
+
+### File system object (SPIFFS)
+
+#### begin
+
+```c++
+SPIFFS.begin()
+```
+
+This method mounts SPIFFS file system. It must be called before any other
+FS APIs are used. Returns *true* if file system was mounted successfully, false
+otherwise.
+
+#### open
+
+```c++
+SPIFFS.open(path, mode)
+```
+
+Opens a file. `path` should be an absolute path starting with a slash
+(e.g. `/dir/filename.txt`). `mode` is a string specifying access mode. It can be
+one of "r", "w", "a", "r+", "w+", "a+". Meaning of these modes is the same as
+for `fopen` C function.
+
+Returns *File* object. To check whether the file was opened successfully, use
+the boolean operator.
+
+```c++
+File f = SPIFFS.open("/f.txt", "w");
+if (!f) {
+    Serial.println("file open failed");
+}
+```
+
+#### openDir
+
+```c++
+SPIFFS.openDir(path)
+```
+
+Opens a directory given its absolute path. Returns a *Dir* object. To check if
+directory was opened successfully, use the boolean operator, similar to opening
+a file.
+
+#### remove
+
+```c++
+SPIFFS.remove(path)
+```
+
+Deletes the file given its absolute path. Returns *true* if file was deleted successfully.
+
+#### rename
+
+```c++
+SPIFFS.rename(pathFrom, pathTo)
+```
+
+Renames file from `pathFrom` to `pathTo`. Paths must be absolute. Returns *true*
+if file was renamed successfully.
+
+### Directory object (Dir)
+
+The purpose of *Dir* object is to iterate over files inside a directory.
+It provides three methods: `next()`, `fileName()`, and `openFile(mode)`.
+
+The following example shows how it should be used:
+
+```c++
+Dir dir = SPIFFS.openDir("/data");
+while (dir.next()) {
+    Serial.print(dir.fileName());
+    File f = dir.openFile("r");
+    Serial.println(f.size());
+}
+```
+
+`dir.next()` returns true while there are files in the directory to iterate over.
+It must be called before calling `fileName` and `openFile` functions.
+
+`openFile` method takes *mode* argument which has the same meaning as for `SPIFFS.open` function.
+
+### File object
+
+`SPIFFS.open` and `dir.openFile` functions return a *File* object. This object
+supports all the functions of *Stream*, so you can use `readBytes`, `findUntil`,
+`parseInt`, `println`, and all other *Stream* methods.
+
+There are also some functions which are specific to *File* object.
+
+#### seek
+
+```c++
+file.seek(offset, mode)
+```
+
+This function behaves like `fseek` C function. Depending on the value of `mode`,
+it moves current position in a file as follows:
+
+- if `mode` is `SeekSet`, position is set to `offset` bytes from the beginning.
+- if `mode` is `SeekCur`, current position is moved by `offset` bytes.
+- if `mode` is `SeekEnd`, position is set to `offset` bytes from the end of the
+file.
+
+Returns *true* if position was set successfully.
+
+#### position
+
+```c++
+file.position()
+```
+
+Returns the current position inside the file, in bytes.
+
+#### size
+
+```c++
+file.size()
+```
+
+Returns file size, in bytes.
+
+
+#### name
+
+```c++
+String name = file.name();
+```
+
+Returns file name, as `const char*`. Convert it to *String* for storage.
+
+#### close
+
+```c++
+file.close()
+```
+
+Close the file. No other operations should be performed on *File* object after `close` function was called.
 
 ## WiFi(ESP8266WiFi library)