Update docs regarding error handling

mkdocs/docs/config/options.md

@@ -13,9 +13,9 @@ These options are the same regardless of whether you use them with the
   which will be converted to pages)
 - STR = string (may refer to an enumerated value, see details of
   argument)
-- FUNC = filesystem function
-- CATEGORY = function category
-- POLICY = mergerfs function policy
+- FUNC = filesystem [function](functions_categories_policies.md)
+- CATEGORY = function [category](functions_categories_policies.md)
+- POLICY = mergerfs function [policy](functions_categories_policies.md)
 
 
 ### mount options

mkdocs/docs/error_handling_and_logging.md

@@ -2,32 +2,53 @@
 
 ## Error Handling
 
-POSIX filesystem functions offer a single return code meaning that
-there is some complication regarding the handling of multiple branches
-as mergerfs does. It tries to handle errors in a way that would
-generally return meaningful values for that particular function.
+POSIX filesystem functions typically work on singular items and return
+singular errors. This means that there is some complication when
+dealing with multiple files or behaviors that are required in mergerfs.
 
-### chmod, chown, removexattr, setxattr, truncate, utimens
+mergerfs tries to handle errors in a way that would generally return
+meaningful values for that particular function.
 
-1. if no error: return 0 (success)
+### Filesystem Functions
+
+#### chmod, chown, removexattr, setxattr, truncate, utimens
+
+1. if no errors: return 0 (success)
 2. if no successes: return first error
-3. if one of the files acted on was the same as the related search function: return its value
+3. if one of the files acted on was the same as the related search
+   function: return its value
 4. return 0 (success)
 
 While doing this increases the complexity and cost of error handling,
 particularly step 3, this provides probably the most reasonable return
 value.
 
-### unlink, rmdir
+
+#### unlink, rmdir
 
 1. if no errors: return 0 (success)
 2. return first error
 
-Older versions of mergerfs would return success if any success occurred
-but for unlink and rmdir there are downstream assumptions that, while
-not impossible to occur, can confuse some software.
+Older versions of mergerfs would return success if any success
+occurred but for unlink and rmdir there are downstream assumptions
+that, while not impossible to occur in more traditional situation, can
+confuse some software.
 
-### others
+#### open, create
+
+For `create` and `open` where a single file is targeted the return
+value of the equivalent final call is returned.
+
+If the error returned is `EROFS`, indicating the filesystem is in fact
+read-only, mergerfs will mark the branch `RO` and rerun the
+policy. This typically will only happen with `ext4` when the
+filesystem is found to have corruption and the OS remounts the
+filesystem as read-only to protect it. In that situation the
+filesystem does not otherwise indicate that it is read-only as it
+would if mounted with `ro`.
+
+
+#### others
 
 For search functions, there is always a single thing acted on and as
 such whatever return value that comes from the single function call is
@@ -39,12 +60,38 @@ policies it will return success if any of the calls succeed and an
 error otherwise.
 
 
+## Branches disappearing / reappearing
+
+This is not an error condition. mergerfs works on paths. Not
+mounts. There is currently no assumption or active inspection of the
+branch path provided at runtime. Nor does it keep its own open file
+descriptors that would prevent an unused filesystem from being
+unmounted. If a filesystem disappears for any reason mergerfs will
+simply continue on behaving as it would normally. As if you never
+mounted that filesystem into that location. If a branch path no longer
+exists the branch is simply skipped by policies.
+
+If you wish to keep the branch path from being used when a branch
+path's intended filesystem disappears then make the directory
+difficult or impossible to use.
+
+```
+chown root:root /mnt/mountpoint/
+chmod 0000 /mnt/mountpoint/
+chattr +i /mnt/mountpoint/
+```
+
+You can still mount to that directory but you will not be able to
+write to it. Even as root. Note that `chattr` works on limited
+filesystems. Mainly `ext4`.
+
+
 ## Logging
 
 Filesystems, and therefore mergerfs, are doing lots of small actions
 at high speed. It simply isn't reasonable to log all the actions of
 the system. That said: certain details are logged at startup and when
-performing mainance tasks. These are logged via `syslog` and on
+performing maintenance tasks. These are logged via `syslog` and on
 `systemd` based systems can be viewed by running
 
 ```

mkdocs/docs/faq/usage_and_functionality.md

@@ -9,15 +9,10 @@ other application does. It can not do anything that any other random
 piece of software can't do.
 
 mergerfs is **not** a traditional filesystem that takes control over
-the underlying disk or block device. mergerfs is **not** RAID. It does
-**not** manipulate the data that passes through it. It does **not**
-shard data across filesystems. It only shards some **behavior** and
-aggregates others.
-
-
-## Can filesystems be removed from the pool without affecting them?
-
-Yes. See previous question's answer.
+the underlying drive, block device, or partition. mergerfs is **not**
+RAID. It does **not** manipulate the data that passes through it. It
+does **not** shard data across filesystems. It only shards some
+**behavior** and aggregates others.
 
 
 ## Can mergerfs be removed without affecting the data?
@@ -25,9 +20,32 @@ Yes. See previous question's answer.
 Yes. See the previous question's answer.
 
 
+## Can filesystems be removed from the pool without affecting them?
+
+Yes. See previous question's answer.
+
+This is true for planned removal by unmounting mergerfs and changing
+the config, changes made to mergerfs at
+[runtime](../runtime_interfaces.md), umounting of the branch's
+filesystem on the fly (whether on purpose or due to error), etc.
+
+
+## What happens if a filesystem disappears at runtime?
+
+By "disappear" meaning explicitly unmounted or due to an error the OS
+removes it.
+
+Nothing explicitly happens. mergerfs works on paths, not mounts. If
+the branch path still exists mergerfs will treat it the same as it did
+before. It just may not have any data there. If the branch no longer
+exists it will be ignored. If the OS returns errors then mergerfs will
+return those errors where appropriate. See [Error Handling and
+Logging](../error_handling_and_logging.md).
+
+
 ## Can filesystems be moved to another pool?
 
-Yes. See the previous question's answer.
+Yes.
 
 
 ## Can filesystems be part of multiple pools?
@@ -37,7 +55,9 @@ Yes.
 
 ## How do I migrate data into or out of the pool when adding/removing filesystems?
 
-There is no need to do so. See the previous questions.
+There is no need to do so. mergerfs is a union filesystem. It works
+**on top** of existing filesystems. It does **not** replace them. See
+the previous questions and answers.
 
 
 ## How do I remove a filesystem but keep the data in the pool?

mkdocs/docs/index.md

@@ -37,9 +37,10 @@ and **aufs**.
 
 ## How it works
 
-mergerfs logically merges multiple filesystem paths together. It acts
-as a proxy to the underlying filesystem paths. Combining the behaviors
-of some functions and being a selector for others.
+mergerfs logically merges multiple filesystem paths together. Not
+block devices, not filesystem mounts, just paths. It acts as a proxy
+to the underlying filesystem paths. Combining the behaviors of some
+functions and being a selector for others.
 
 When the contents of a directory are requested mergerfs combines the
 list of files from each directory, deduplicating entries, and returns
@@ -77,3 +78,7 @@ A         +      B        =       C
                                   |
                                   +-- file6
 ```
+
+## Getting Started
+
+Head to the [quick start guide](quickstart.md).