Merge pull request #275 from trapexit/updateman

update man page

Makefile

@@ -134,7 +134,7 @@ obj/%.o: src/%.cpp
 clean: rpm-clean
 	$(RM) -rf obj
 	$(RM) -f src/version.hpp
-	$(RM) -f "$(TARGET)" "$(MANPAGE)" mount.mergerfs
+	$(RM) -f "$(TARGET)" mount.mergerfs
 	$(FIND) . -name "*~" -delete
 
 distclean: clean
@@ -150,7 +150,7 @@ install-mount.mergerfs: mount.mergerfs
 	$(CP) -a "$<" "$(INSTALLBINDIR)/$<"
 
 install-man: $(MANPAGE)
-	$(INSTALL) -v -m 0644 -D "$(MANPAGE)" "$(INSTALLMAN1DIR)/$(MANPAGE)"
+	$(INSTALL) -v -m 0644 -D "man/$(MANPAGE)" "$(INSTALLMAN1DIR)/$(MANPAGE)"
 
 install-strip: install-base
 	$(STRIP) "$(INSTALLBINDIR)/$(TARGET)"
@@ -168,9 +168,7 @@ uninstall-man:
 
 $(MANPAGE): README.md
 ifneq (,$(PANDOC))
-	$(PANDOC) -s -t man -o $(MANPAGE) README.md
-else
-	$(CP) man/mergerfs.1 .
+	$(PANDOC) -s -t man -o "man/$(MANPAGE)" README.md
 endif
 
 man: $(MANPAGE)

README.md

@@ -1,6 +1,6 @@
 % mergerfs(1) mergerfs user manual
 % Antonio SJ Musumeci <trapexit@spawn.link>
-% 2016-02-21
+% 2016-05-03
 
 # NAME
 
@@ -37,33 +37,38 @@ mergerfs -o&lt;options&gt; &lt;srcmounts&gt; &lt;mountpoint&gt;
 * **moveonenospc**: when enabled (set to **true**) if a **write** fails with **ENOSPC** a scan of all drives will be done looking for the drive with most free space which is at least the size of the file plus the amount which failed to write. An attempt to move the file to that drive will occur (keeping all metadata possible) and if successful the original is unlinked and the write retried. (default: false)
 * **func.&lt;func&gt;=&lt;policy&gt;**: sets the specific FUSE function's policy. See below for the list of value types. Example: **func.getattr=newest**
 * **category.&lt;category&gt;=&lt;policy&gt;**: Sets policy of all FUSE functions in the provided category. Example: **category.create=mfs**
+* **fsname**: sets the name of the filesystem as seen in **mount**, **df**, etc. Defaults to a list of the source paths concatenated together with the longest common prefix removed.
 
 **NOTE:** Options are evaluated in the order listed so if the options are **func.rmdir=rand,category.action=ff** the **action** category setting will override the **rmdir** setting.
 
 ###srcmounts###
 
-The source mounts argument is a colon (':') delimited list of paths. To make it simpler to include multiple source mounts without having to modify your [fstab](http://linux.die.net/man/5/fstab) we also support [globbing](http://linux.die.net/man/7/glob). **The globbing tokens MUST be escaped when using via the shell else the shell itself will probably expand it.**
+The srcmounts (source mounts) argument is a colon (':') delimited list of paths to be included in the pool. It does not matter if the paths are on the same or different drives nor does it matter the filesystem. Used and available space will not be duplicated for paths on the same device and any features which aren't supported by the underlying filesystem (such as file attributes or extended attributes) will return the appropriate errors.
+
+To make it easier to include multiple source mounts mergerfs supports [globbing](http://linux.die.net/man/7/glob). **The globbing tokens MUST be escaped when using via the shell else the shell itself will expand it.**
 
 ```
-$ mergerfs /mnt/disk\*:/mnt/cdrom /media/drives
+$ mergerfs -o defaults,allow_other /mnt/disk\*:/mnt/cdrom /media/drives
 ```
 
-The above line will use all mount points in /mnt prefixed with *disk* and the directory *cdrom*.
+The above line will use all mount points in /mnt prefixed with **disk** and the **cdrom**.
 
-In /etc/fstab it'd look like the following:
+To have the pool mounted at boot or otherwise accessable from related tools use **/etc/fstab**.
 
 ```
 # <file system>        <mount point>  <type>         <options>             <dump>  <pass>
 /mnt/disk*:/mnt/cdrom  /media/drives  fuse.mergerfs  defaults,allow_other  0       0
 ```
 
-**NOTE:** the globbing is done at mount or xattr update time. If a new directory is added matching the glob after the fact it will not be included.
+**NOTE:** the globbing is done at mount or xattr update time (see below). If a new directory is added matching the glob after the fact it will not be automatically included.
+
+**NOTE:** for mounting via **fstab** to work you must have **mount.fuse** installed. For Ubuntu/Debian it is included in the **fuse** package.
 
 # FUNCTIONS / POLICIES / CATEGORIES
 
-The filesystem has a number of functions. Those functions are grouped into 3 categories: **action**, **create**, **search**. These functions and categories can be assigned a policy which dictates how **mergerfs** behaves. Any policy can be assigned to a function or category though some are not very practical. For instance: **rand** (Random) may be useful for file creation (create) but could lead to very odd behavior if used for `chmod`.
+The POSIX filesystem API has a number of functions. **creat**, **stat**, **chown**, etc. In mergerfs these functions are grouped into 3 categories: **action**, **create**, and **search**. Functions and categories can be assigned a policy which dictates how **mergerfs** behaves. Any policy can be assigned to a function or category though some are not very practical. For instance: **rand** (random) may be useful for file creation (create) but could lead to very odd behavior if used for `chmod` (though only if there were more than one copy of the file).
 
-All policies when used to create will ignore drives which are mounted readonly. This allows for read/write and readonly drives to be mixed together.
+Policies, when called to create, will ignore drives which are readonly or have less than **minfreespace**. This allows for read/write and readonly drives to be mixed together and keep drives which may remount as readonly on error from further affecting the pool.
 
 #### Function / Category classifications ####
 
@@ -74,22 +79,22 @@ All policies when used to create will ignore drives which are mounted readonly.
 | search   | access, getattr, getxattr, ioctl, listxattr, open, readlink |
 | N/A      | fallocate, fgetattr, fsync, ftruncate, ioctl, read, readdir, release, statfs, write |
 
-Due to FUSE limitations **ioctl** behaves differently if its acting on a directory. It'll use the **getattr** policy to find and open the directory before issuing the **ioctl**. In other cases where something may be searched (to confirm a directory exists across all source mounts) then **getattr** will be used.
+Due to FUSE limitations **ioctl** behaves differently if its acting on a directory. It'll use the **getattr** policy to find and open the directory before issuing the **ioctl**. In other cases where something may be searched (to confirm a directory exists across all source mounts) **getattr** will also be used.
 
 #### Policy descriptions ####
 
-Most policies when called to create will filter out drives which are readonly or have less than **minfreespace**.
-
 | Policy | Description |
 |--------------|-------------|
-| all | Search category: acts like **ff**. Action category: apply to all found. Create category: for **mkdir**, **mknod**, and **symlink** perform on all read/write drives with **minfreespace**. **create** filters the same way but acts like **ff**. |
-| eplfs (existing path, least free space) | If the path exists on multiple drives use the one with the least free space. Falls back to **lfs**. |
-| epmfs (existing path, most free space) | If the path exists on multiple drives use the one with the most free space. Falls back to **mfs**. |
+| all | Search category: acts like **ff**. Action category: apply to all found. Create category: for **mkdir**, **mknod**, and **symlink** it will apply to all found. **create** works like **ff**. It will exclude readonly drives and those with free space less than **minfreespace**. |
+| eplfs (existing path, least free space) | If the path exists on multiple drives use the one with the least free space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **lfs**. |
+| eplus (existing path, least used space) | If the path exists on multiple drives the the one with the least used space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **lus**. |
+| epmfs (existing path, most free space) | If the path exists on multiple drives use the one with the most free space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **mfs**. |
 | erofs | Exclusively return **-1** with **errno** set to **EROFS**. By setting **create** functions to this you can in effect turn the filesystem readonly. |
-| ff (first found) | Given the order of the drives, as defined at mount time or when configured via xattr interface, act on the first one found. |
-| lfs (least free space) | Pick the drive with the least available free space but more than **minfreespace**. Falls back to **mfs**. |
-| mfs (most free space) | Use the drive with the most available free space. Falls back to **ff**. |
-| newest (newest file) | Pick the file / directory with the largest mtime. |
+| ff (first found) | Given the order of the drives, as defined at mount time or when configured via xattr interface, act on the first one found. For **create** category it will exclude readonly drives and those with free space less than **minfreespace** (unless there is no other option). |
+| lfs (least free space) | Pick the drive with the least available free space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **mfs**. |
+| lus (least used space) | Pick the drive with the least used space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **mfs**. |
+| mfs (most free space) | Pick the drive with the most available free space. For **create** category it will exclude readonly drives and those with free space less than **minfreespace**. Falls back to **ff**. |
+| newest (newest file) | Pick the file / directory with the largest mtime. For **create** category it will exclude readonly drives and those with free space less than **minfreespace** (unless there is no other option). |
 | rand (random) | Calls **all** and then randomizes. |
 
 #### Defaults ####
@@ -102,14 +107,14 @@ Most policies when called to create will filter out drives which are readonly or
 
 #### rename & link ####
 
-[rename](http://man7.org/linux/man-pages/man2/rename.2.html) is a tricky function in a merged system. Normally if a rename can't be done atomically due to the source and destination paths existing on different mount points it will return `-1` with `errno = EXDEV`. The atomic rename is most critical for replacing files in place atomically (such as securing writing to a temp file and then replacing a target). The problem is that by merging multiple paths you can have N instances of the source and destinations on different drives. This can lead to several undesirable situtations with or without errors and it's not entirely obvious what to do when an error occurs.
+[rename](http://man7.org/linux/man-pages/man2/rename.2.html) is a tricky function in a merged system. Normally if a rename can't be done atomically due to the source and destination paths existing on different mount points it will return **-1** with **errno = EXDEV**. The atomic rename is most critical for replacing files in place atomically (such as securing writing to a temp file and then replacing a target). The problem is that by merging multiple paths you can have N instances of the source and destinations on different drives. This can lead to several undesirable situtations with or without errors and it's not entirely obvious what to do when an error occurs.
 
 Originally mergerfs would return EXDEV whenever a rename was requested which was cross directory in any way. This made the code simple and was technically complient with POSIX requirements. However, many applications fail to handle EXDEV at all and treat it as a normal error or they only partially support EXDEV (don't respond the same as `mv` would). Such apps include: gvfsd-fuse v1.20.3 and prior, Finder / CIFS/SMB client in Apple OSX 10.9+, NZBGet, Samba's recycling bin feature.
 
-* If using a `create` policy which tries to preserve directory paths (epmfs,eplfs)
-  * Using the `rename` policy get the list of files to rename
+* If using a **create** policy which tries to preserve directory paths (epmfs,eplfs)
+  * Using the **rename** policy get the list of files to rename
   * For each file attempt rename:
-    * If failure with ENOENT run `create` policy
+    * If failure with ENOENT run **create** policy
     * If create policy returns the same drive as currently evaluating then clone the path
     * Re-attempt rename
   * If **any** of the renames succeed the higher level rename is considered a success
@@ -117,9 +122,9 @@ Originally mergerfs would return EXDEV whenever a rename was requested which was
   * On success:
     * Remove the target from all drives with no source file
     * Remove the source from all drives which failed to rename
-* If using a `create` policy which does **not** try to preserve directory paths
-  * Using the `rename` policy get the list of files to rename
-  * Using the `getattr` policy get the target path
+* If using a **create** policy which does **not** try to preserve directory paths
+  * Using the **rename** policy get the list of files to rename
+  * Using the **getattr** policy get the target path
   * For each file attempt rename:
     * If the source drive != target drive:
       * Clone target path from target drive to source drive
@@ -132,15 +137,13 @@ Originally mergerfs would return EXDEV whenever a rename was requested which was
 
 The the removals are subject to normal entitlement checks.
 
-The above behavior will help minimize the likelihood of EXDEV being returned but it will still be possible. To remove the possibility all together mergerfs would need to perform the as `mv` does when it receives EXDEV normally.
+The above behavior will help minimize the likelihood of EXDEV being returned but it will still be possible. To remove the possibility all together mergerfs would need to perform the as **mv** does when it receives EXDEV normally.
 
-`link` uses the same basic strategy.
+**link** uses the same basic strategy.
 
 #### readdir ####
 
-[readdir](http://linux.die.net/man/3/readdir) is different from all other filesystem functions. It certainly could have it's own set of policies to tweak its behavior. At this time it provides a simple **first found** merging of directories and files found. That is: only the first file or directory found for a directory is returned. Given how FUSE works though the data representing the returned entry comes from **getattr**.
-
-It could be extended to offer the ability to see all files found. Perhaps concatenating **#** and a number to the name. But to really be useful you'd need to be able to access them which would complicate file lookup.
+[readdir](http://linux.die.net/man/3/readdir) is different from all other filesystem functions. While it could have it's own set of policies to tweak its behavior at this time it provides a simple union of files and directories found. Remember that any action or information queried about these files and directories come from the respective function. For instance: an **ls** is a **readdir** and for each file/directory returned **getattr** is called. Meaning the policy of **getattr** is responsible for choosing the file/directory which is the source of the metadata you see in an **ls**.
 
 #### statvfs ####
 
@@ -155,7 +158,7 @@ First get the code from [github](http://github.com/trapexit/mergerfs).
 ```
 $ git clone https://github.com/trapexit/mergerfs.git
 $ # or
-$ wget https://github.com/trapexit/mergerfs/archive/master.zip
+$ wget https://github.com/trapexit/mergerfs/releases/download/<ver>/mergerfs-<ver>.tar.gz
 ```
 
 #### Debian / Ubuntu
@@ -195,38 +198,40 @@ $ sudo make install
 
 There is a pseudo file available at the mount point which allows for the runtime modification of certain **mergerfs** options. The file will not show up in **readdir** but can be **stat**'ed and manipulated via [{list,get,set}xattrs](http://linux.die.net/man/2/listxattr) calls.
 
-Even if xattrs are disabled the [{list,get,set}xattrs](http://linux.die.net/man/2/listxattr) calls will still work.
+Even if xattrs are disabled for mergerfs the [{list,get,set}xattrs](http://linux.die.net/man/2/listxattr) calls against this pseudo file will still work.
+
+Any changes made at runtime are **not** persisted. If you wish for values to persist they must be included as options wherever you configure the mounting of mergerfs (fstab).
 
 ##### Keys #####
 
-Use `xattr -l /mount/point/.mergerfs` to see all supported keys.
+Use `xattr -l /mount/point/.mergerfs` to see all supported keys. Some are informational and therefore readonly.
 
-##### user.mergerfs.srcmounts #####
+###### user.mergerfs.srcmounts ######
 
-For **user.mergerfs.srcmounts** there are several instructions available for manipulating the list. The value provided is just as the value used at mount time. A colon (':') delimited list of full path globs.
+Used to query or modify the list of source mounts. When modifying there are several shortcuts to easy manipulation of the list.
 
-| Instruction | Description |
+| Value        | Description |
 |--------------|-------------|
-| [list]       | set |
-| +<[list]     | prepend |
-| +>[list]     | append |
+| [list]       | set         |
+| +<[list]     | prepend     |
+| +>[list]     | append      |
 | -[list]      | remove all values provided |
 | -<           | remove first in list |
 | ->           | remove last in list |
 
-##### minfreespace #####
+###### minfreespace ######
 
 Input: interger with an optional multiplier suffix. **K**, **M**, or **G**.
 
 Output: value in bytes
 
-##### moveonenospc #####
+###### moveonenospc ######
 
 Input: **true** and **false**
 
 Ouput: **true** or **false**
 
-##### categories / funcs #####
+###### categories / funcs ######
 
 Input: short policy string as described elsewhere in this document
 
@@ -261,7 +266,7 @@ newest
 /tmp/a:/tmp/b:/tmp/c
 ```
 
-#### mergerfs file xattrs ####
+#### file / directory xattrs ####
 
 While they won't show up when using [listxattr](http://linux.die.net/man/2/listxattr) **mergerfs** offers a number of special xattrs to query information about the files served. To access the values you will need to issue a [getxattr](http://linux.die.net/man/2/getxattr) for one of the following:
 
@@ -286,15 +291,17 @@ A B C
 
 # TOOLING
 
-Find tooling to help with managing `mergerfs` at: https://github.com/trapexit/mergerfs-tools
+Find tooling to help with managing **mergerfs** at: https://github.com/trapexit/mergerfs-tools
 
 * mergerfs.fsck: Provides permissions and ownership auditing and the ability to fix them
+* mergerfs.dedup: Will help identify and optionally remove duplicate files
 * mergerfs.mktrash: Creates FreeDesktop.org Trash specification compatible directories on a mergerfs mount
 
 # TIPS / NOTES
 
-* Detailed guides to setting up a backup solution using mergerfs and other technologies: https://github.com/trapexit/backup-and-recovery-howtos
+* https://github.com/trapexit/backup-and-recovery-howtos : A set of guides / howtos on creating a data storage system, backing it up, maintaining it, and recovering from failure.
 * If you don't see some directories / files you expect in a merged point be sure the user has permission to all the underlying directories. If `/drive0/a` has is owned by `root:root` with ACLs set to `0700` and `/drive1/a` is `root:root` and `0755` you'll see only `/drive1/a`. Use `mergerfs.fsck` to audit the drive for out of sync permissions.
+* Do *not* use `direct_io` if you expect applications (such as rtorrent) to [mmap](http://linux.die.net/man/2/mmap) files. It is not currently supported in FUSE w/ `direct_io` enabled.
 * Since POSIX gives you only error or success on calls its difficult to determine the proper behavior when applying the behavior to multiple targets. **mergerfs** will return an error only if all attempts of an action fail. Any success will lead to a success returned.
 * The recommended options are **defaults,allow_other**. The **allow_other** is to allow users who are not the one which executed mergerfs access to the mountpoint. **defaults** is described above and should offer the best performance. It's possible that if you're running on an older platform the **splice** features aren't available and could error. In that case simply use the other options manually.
 * If write performance is valued more than read it may be useful to enable **direct_io**. Best to benchmark with and without and choose appropriately.
@@ -304,6 +311,14 @@ Find tooling to help with managing `mergerfs` at: https://github.com/trapexit/me
 
 # KNOWN ISSUES / BUGS
 
+#### rtorrent fails with ENODEV (No such device)
+
+Be sure to turn off `direct_io`. rtorrent and some other applications use [mmap](http://linux.die.net/man/2/mmap) to read and write to files and offer no failback to traditional methods. FUSE does not currently support mmap while using `direct_io`. There will be a performance penalty on writes with `direct_io` off but it's the only way to get such applications to work. If the performance loss is too high for other apps you can mount mergerfs twice. Once with `direct_io` enabled and one without it.
+
+#### mmap performance is really bad
+
+There [appears to be a bug](https://lkml.org/lkml/2016/3/16/260) in caching which affects overall performance of mmap through FUSE in Linux 4.x kernels.
+
 #### Trashing files occasionally fails
 
 This is the same issue as with Samba. `rename` returns `EXDEV` (in our case that will really only happen with path preserving policies like `epmfs`) and the software doesn't handle the situtation well. This is unfortunately a common failure of software which moves files around. The standard indicates that an implementation `MAY` choose to support non-user home directory trashing of files (which is a `MUST`). The implementation `MAY` also support "top directory trashes" which many probably do. 
@@ -346,6 +361,10 @@ While aufs can offer better peak performance mergerfs offers more configurabilit
 
 A single drive failure will lead to full pool failure without additional redundancy. mergerfs performs a similar behavior without the catastrophic failure and lack of recovery. Drives can fail and all other data will continue to be accessable.
 
+#### Can drives be written to directly? Outside of mergerfs while pooled?
+
+Yes. It will be represented immediately in the pool as the policies would describe.
+
 #### It's mentioned that there are some security issues with mhddfs. What are they? How does mergerfs address them?
 
 [mhddfs](https://github.com/trapexit/mhddfs) tries to handle being run as **root** by calling [getuid()](https://github.com/trapexit/mhddfs/blob/cae96e6251dd91e2bdc24800b4a18a74044f6672/src/main.c#L319) and if it returns **0** then it will [chown](http://linux.die.net/man/1/chown) the file. Not only is that a race condition but it doesn't handle many other situations. Rather than attempting to simulate POSIX ACL behaviors the proper behavior is to use [seteuid](http://linux.die.net/man/2/seteuid) and [setegid](http://linux.die.net/man/2/setegid), become the user making the original call and perform the action as them. This is how [mergerfs](https://github.com/trapexit/mergerfs) handles things.
@@ -371,3 +390,9 @@ For non-Linux systems mergerfs uses a read-write lock and changes credentials on
 #### Support development
 * Gratipay: https://gratipay.com/~trapexit
 * BitCoin: 12CdMhEPQVmjz3SSynkAEuD5q9JmhTDCZA
+
+# LINKS
+
+* http://github.com/trapexit/mergerfs
+* http://github.com/trapexit/mergerfs-tools
+* http://github.com/trapexit/backup-and-recovery-howtos

man/mergerfs.1

@@ -1,5 +1,5 @@
 .\"t
-.TH "mergerfs" "1" "2016\-02\-21" "mergerfs user manual" ""
+.TH "mergerfs" "1" "2016\-05\-03" "mergerfs user manual" ""
 .SH NAME
 .PP
 mergerfs \- another (FUSE based) union filesystem
@@ -67,6 +67,11 @@ Example: \f[B]func.getattr=newest\f[]
 \f[B]category.<category>=<policy>\f[]: Sets policy of all FUSE functions
 in the provided category.
 Example: \f[B]category.create=mfs\f[]
+.IP \[bu] 2
+\f[B]fsname\f[]: sets the name of the filesystem as seen in
+\f[B]mount\f[], \f[B]df\f[], etc.
+Defaults to a list of the source paths concatenated together with the
+longest common prefix removed.
 .PP
 \f[B]NOTE:\f[] Options are evaluated in the order listed so if the
 options are \f[B]func.rmdir=rand,category.action=ff\f[] the
@@ -74,24 +79,31 @@ options are \f[B]func.rmdir=rand,category.action=ff\f[] the
 setting.
 .SS srcmounts
 .PP
-The source mounts argument is a colon (\[aq]:\[aq]) delimited list of
-paths.
-To make it simpler to include multiple source mounts without having to
-modify your fstab (http://linux.die.net/man/5/fstab) we also support
+The srcmounts (source mounts) argument is a colon (\[aq]:\[aq])
+delimited list of paths to be included in the pool.
+It does not matter if the paths are on the same or different drives nor
+does it matter the filesystem.
+Used and available space will not be duplicated for paths on the same
+device and any features which aren\[aq]t supported by the underlying
+filesystem (such as file attributes or extended attributes) will return
+the appropriate errors.
+.PP
+To make it easier to include multiple source mounts mergerfs supports
 globbing (http://linux.die.net/man/7/glob).
 \f[B]The globbing tokens MUST be escaped when using via the shell else
-the shell itself will probably expand it.\f[]
+the shell itself will expand it.\f[]
 .IP
 .nf
 \f[C]
-$\ mergerfs\ /mnt/disk\\*:/mnt/cdrom\ /media/drives
+$\ mergerfs\ \-o\ defaults,allow_other\ /mnt/disk\\*:/mnt/cdrom\ /media/drives
 \f[]
 .fi
 .PP
 The above line will use all mount points in /mnt prefixed with
-\f[I]disk\f[] and the directory \f[I]cdrom\f[].
+\f[B]disk\f[] and the \f[B]cdrom\f[].
 .PP
-In /etc/fstab it\[aq]d look like the following:
+To have the pool mounted at boot or otherwise accessable from related
+tools use \f[B]/etc/fstab\f[].
 .IP
 .nf
 \f[C]
@@ -100,24 +112,33 @@ In /etc/fstab it\[aq]d look like the following:
 \f[]
 .fi
 .PP
-\f[B]NOTE:\f[] the globbing is done at mount or xattr update time.
+\f[B]NOTE:\f[] the globbing is done at mount or xattr update time (see
+below).
 If a new directory is added matching the glob after the fact it will not
-be included.
+be automatically included.
+.PP
+\f[B]NOTE:\f[] for mounting via \f[B]fstab\f[] to work you must have
+\f[B]mount.fuse\f[] installed.
+For Ubuntu/Debian it is included in the \f[B]fuse\f[] package.
 .SH FUNCTIONS / POLICIES / CATEGORIES
 .PP
-The filesystem has a number of functions.
-Those functions are grouped into 3 categories: \f[B]action\f[],
-\f[B]create\f[], \f[B]search\f[].
-These functions and categories can be assigned a policy which dictates
-how \f[B]mergerfs\f[] behaves.
+The POSIX filesystem API has a number of functions.
+\f[B]creat\f[], \f[B]stat\f[], \f[B]chown\f[], etc.
+In mergerfs these functions are grouped into 3 categories:
+\f[B]action\f[], \f[B]create\f[], and \f[B]search\f[].
+Functions and categories can be assigned a policy which dictates how
+\f[B]mergerfs\f[] behaves.
 Any policy can be assigned to a function or category though some are not
 very practical.
-For instance: \f[B]rand\f[] (Random) may be useful for file creation
-(create) but could lead to very odd behavior if used for \f[C]chmod\f[].
+For instance: \f[B]rand\f[] (random) may be useful for file creation
+(create) but could lead to very odd behavior if used for \f[C]chmod\f[]
+(though only if there were more than one copy of the file).
 .PP
-All policies when used to create will ignore drives which are mounted
-readonly.
-This allows for read/write and readonly drives to be mixed together.
+Policies, when called to create, will ignore drives which are readonly
+or have less than \f[B]minfreespace\f[].
+This allows for read/write and readonly drives to be mixed together and
+keep drives which may remount as readonly on error from further
+affecting the pool.
 .SS Function / Category classifications
 .PP
 .TS
@@ -158,12 +179,9 @@ on a directory.
 It\[aq]ll use the \f[B]getattr\f[] policy to find and open the directory
 before issuing the \f[B]ioctl\f[].
 In other cases where something may be searched (to confirm a directory
-exists across all source mounts) then \f[B]getattr\f[] will be used.
+exists across all source mounts) \f[B]getattr\f[] will also be used.
 .SS Policy descriptions
 .PP
-Most policies when called to create will filter out drives which are
-readonly or have less than \f[B]minfreespace\f[].
-.PP
 .TS
 tab(@);
 l l.
@@ -179,22 +197,36 @@ T}@T{
 Search category: acts like \f[B]ff\f[].
 Action category: apply to all found.
 Create category: for \f[B]mkdir\f[], \f[B]mknod\f[], and
-\f[B]symlink\f[] perform on all read/write drives with
+\f[B]symlink\f[] it will apply to all found.
+\f[B]create\f[] works like \f[B]ff\f[].
+It will exclude readonly drives and those with free space less than
 \f[B]minfreespace\f[].
-\f[B]create\f[] filters the same way but acts like \f[B]ff\f[].
 T}
 T{
 eplfs (existing path, least free space)
 T}@T{
 If the path exists on multiple drives use the one with the least free
 space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
 Falls back to \f[B]lfs\f[].
 T}
 T{
+eplus (existing path, least used space)
+T}@T{
+If the path exists on multiple drives the the one with the least used
+space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
+Falls back to \f[B]lus\f[].
+T}
+T{
 epmfs (existing path, most free space)
 T}@T{
 If the path exists on multiple drives use the one with the most free
 space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
 Falls back to \f[B]mfs\f[].
 T}
 T{
@@ -210,24 +242,41 @@ ff (first found)
 T}@T{
 Given the order of the drives, as defined at mount time or when
 configured via xattr interface, act on the first one found.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[] (unless there is no
+other option).
 T}
 T{
 lfs (least free space)
 T}@T{
-Pick the drive with the least available free space but more than
-\f[B]minfreespace\f[].
+Pick the drive with the least available free space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
+Falls back to \f[B]mfs\f[].
+T}
+T{
+lus (least used space)
+T}@T{
+Pick the drive with the least used space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
 Falls back to \f[B]mfs\f[].
 T}
 T{
 mfs (most free space)
 T}@T{
-Use the drive with the most available free space.
+Pick the drive with the most available free space.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[].
 Falls back to \f[B]ff\f[].
 T}
 T{
 newest (newest file)
 T}@T{
 Pick the file / directory with the largest mtime.
+For \f[B]create\f[] category it will exclude readonly drives and those
+with free space less than \f[B]minfreespace\f[] (unless there is no
+other option).
 T}
 T{
 rand (random)
@@ -268,7 +317,7 @@ rename (http://man7.org/linux/man-pages/man2/rename.2.html) is a tricky
 function in a merged system.
 Normally if a rename can\[aq]t be done atomically due to the source and
 destination paths existing on different mount points it will return
-\f[C]\-1\f[] with \f[C]errno\ =\ EXDEV\f[].
+\f[B]\-1\f[] with \f[B]errno = EXDEV\f[].
 The atomic rename is most critical for replacing files in place
 atomically (such as securing writing to a temp file and then replacing a
 target).
@@ -287,15 +336,15 @@ same as \f[C]mv\f[] would).
 Such apps include: gvfsd\-fuse v1.20.3 and prior, Finder / CIFS/SMB
 client in Apple OSX 10.9+, NZBGet, Samba\[aq]s recycling bin feature.
 .IP \[bu] 2
-If using a \f[C]create\f[] policy which tries to preserve directory
+If using a \f[B]create\f[] policy which tries to preserve directory
 paths (epmfs,eplfs)
 .IP \[bu] 2
-Using the \f[C]rename\f[] policy get the list of files to rename
+Using the \f[B]rename\f[] policy get the list of files to rename
 .IP \[bu] 2
 For each file attempt rename:
 .RS 2
 .IP \[bu] 2
-If failure with ENOENT run \f[C]create\f[] policy
+If failure with ENOENT run \f[B]create\f[] policy
 .IP \[bu] 2
 If create policy returns the same drive as currently evaluating then
 clone the path
@@ -317,12 +366,12 @@ Remove the target from all drives with no source file
 Remove the source from all drives which failed to rename
 .RE
 .IP \[bu] 2
-If using a \f[C]create\f[] policy which does \f[B]not\f[] try to
+If using a \f[B]create\f[] policy which does \f[B]not\f[] try to
 preserve directory paths
 .IP \[bu] 2
-Using the \f[C]rename\f[] policy get the list of files to rename
+Using the \f[B]rename\f[] policy get the list of files to rename
 .IP \[bu] 2
-Using the \f[C]getattr\f[] policy get the target path
+Using the \f[B]getattr\f[] policy get the target path
 .IP \[bu] 2
 For each file attempt rename:
 .RS 2
@@ -353,26 +402,22 @@ The the removals are subject to normal entitlement checks.
 The above behavior will help minimize the likelihood of EXDEV being
 returned but it will still be possible.
 To remove the possibility all together mergerfs would need to perform
-the as \f[C]mv\f[] does when it receives EXDEV normally.
+the as \f[B]mv\f[] does when it receives EXDEV normally.
 .PP
-\f[C]link\f[] uses the same basic strategy.
+\f[B]link\f[] uses the same basic strategy.
 .SS readdir
 .PP
 readdir (http://linux.die.net/man/3/readdir) is different from all other
 filesystem functions.
-It certainly could have it\[aq]s own set of policies to tweak its
-behavior.
-At this time it provides a simple \f[B]first found\f[] merging of
-directories and files found.
-That is: only the first file or directory found for a directory is
-returned.
-Given how FUSE works though the data representing the returned entry
-comes from \f[B]getattr\f[].
-.PP
-It could be extended to offer the ability to see all files found.
-Perhaps concatenating \f[B]#\f[] and a number to the name.
-But to really be useful you\[aq]d need to be able to access them which
-would complicate file lookup.
+While it could have it\[aq]s own set of policies to tweak its behavior
+at this time it provides a simple union of files and directories found.
+Remember that any action or information queried about these files and
+directories come from the respective function.
+For instance: an \f[B]ls\f[] is a \f[B]readdir\f[] and for each
+file/directory returned \f[B]getattr\f[] is called.
+Meaning the policy of \f[B]getattr\f[] is responsible for choosing the
+file/directory which is the source of the metadata you see in an
+\f[B]ls\f[].
 .SS statvfs
 .PP
 statvfs (http://linux.die.net/man/2/statvfs) normalizes the source
@@ -393,7 +438,7 @@ First get the code from github (http://github.com/trapexit/mergerfs).
 \f[C]
 $\ git\ clone\ https://github.com/trapexit/mergerfs.git
 $\ #\ or
-$\ wget\ https://github.com/trapexit/mergerfs/archive/master.zip
+$\ wget\ https://github.com/trapexit/mergerfs/releases/download/<ver>/mergerfs\-<ver>.tar.gz
 \f[]
 .fi
 .SS Debian / Ubuntu
@@ -444,25 +489,29 @@ The file will not show up in \f[B]readdir\f[] but can be
 \f[B]stat\f[]\[aq]ed and manipulated via
 {list,get,set}xattrs (http://linux.die.net/man/2/listxattr) calls.
 .PP
-Even if xattrs are disabled the
-{list,get,set}xattrs (http://linux.die.net/man/2/listxattr) calls will
-still work.
+Even if xattrs are disabled for mergerfs the
+{list,get,set}xattrs (http://linux.die.net/man/2/listxattr) calls
+against this pseudo file will still work.
+.PP
+Any changes made at runtime are \f[B]not\f[] persisted.
+If you wish for values to persist they must be included as options
+wherever you configure the mounting of mergerfs (fstab).
 .SS Keys
 .PP
 Use \f[C]xattr\ \-l\ /mount/point/.mergerfs\f[] to see all supported
 keys.
+Some are informational and therefore readonly.
 .SS user.mergerfs.srcmounts
 .PP
-For \f[B]user.mergerfs.srcmounts\f[] there are several instructions
-available for manipulating the list.
-The value provided is just as the value used at mount time.
-A colon (\[aq]:\[aq]) delimited list of full path globs.
+Used to query or modify the list of source mounts.
+When modifying there are several shortcuts to easy manipulation of the
+list.
 .PP
 .TS
 tab(@);
 l l.
 T{
-Instruction
+Value
 T}@T{
 Description
 T}
@@ -546,7 +595,7 @@ newest
 /tmp/a:/tmp/b:/tmp/c
 \f[]
 .fi
-.SS mergerfs file xattrs
+.SS file / directory xattrs
 .PP
 While they won\[aq]t show up when using
 listxattr (http://linux.die.net/man/2/listxattr) \f[B]mergerfs\f[]
@@ -584,18 +633,21 @@ A\ B\ C
 .fi
 .SH TOOLING
 .PP
-Find tooling to help with managing \f[C]mergerfs\f[] at:
+Find tooling to help with managing \f[B]mergerfs\f[] at:
 https://github.com/trapexit/mergerfs\-tools
 .IP \[bu] 2
 mergerfs.fsck: Provides permissions and ownership auditing and the
 ability to fix them
 .IP \[bu] 2
+mergerfs.dedup: Will help identify and optionally remove duplicate files
+.IP \[bu] 2
 mergerfs.mktrash: Creates FreeDesktop.org Trash specification compatible
 directories on a mergerfs mount
 .SH TIPS / NOTES
 .IP \[bu] 2
-Detailed guides to setting up a backup solution using mergerfs and other
-technologies: https://github.com/trapexit/backup\-and\-recovery\-howtos
+https://github.com/trapexit/backup\-and\-recovery\-howtos : A set of
+guides / howtos on creating a data storage system, backing it up,
+maintaining it, and recovering from failure.
 .IP \[bu] 2
 If you don\[aq]t see some directories / files you expect in a merged
 point be sure the user has permission to all the underlying directories.
@@ -605,6 +657,10 @@ to \f[C]0700\f[] and \f[C]/drive1/a\f[] is \f[C]root:root\f[] and
 Use \f[C]mergerfs.fsck\f[] to audit the drive for out of sync
 permissions.
 .IP \[bu] 2
+Do \f[I]not\f[] use \f[C]direct_io\f[] if you expect applications (such
+as rtorrent) to mmap (http://linux.die.net/man/2/mmap) files.
+It is not currently supported in FUSE w/ \f[C]direct_io\f[] enabled.
+.IP \[bu] 2
 Since POSIX gives you only error or success on calls its difficult to
 determine the proper behavior when applying the behavior to multiple
 targets.
@@ -653,6 +709,23 @@ Due to previously mentioned issues its generally best to set
 This will help limit the confusion of tools such as
 rsync (http://linux.die.net/man/1/rsync).
 .SH KNOWN ISSUES / BUGS
+.SS rtorrent fails with ENODEV (No such device)
+.PP
+Be sure to turn off \f[C]direct_io\f[].
+rtorrent and some other applications use
+mmap (http://linux.die.net/man/2/mmap) to read and write to files and
+offer no failback to traditional methods.
+FUSE does not currently support mmap while using \f[C]direct_io\f[].
+There will be a performance penalty on writes with \f[C]direct_io\f[]
+off but it\[aq]s the only way to get such applications to work.
+If the performance loss is too high for other apps you can mount
+mergerfs twice.
+Once with \f[C]direct_io\f[] enabled and one without it.
+.SS mmap performance is really bad
+.PP
+There appears to be a bug (https://lkml.org/lkml/2016/3/16/260) in
+caching which affects overall performance of mmap through FUSE in Linux
+4.x kernels.
 .SS Trashing files occasionally fails
 .PP
 This is the same issue as with Samba.
@@ -772,6 +845,11 @@ redundancy.
 mergerfs performs a similar behavior without the catastrophic failure
 and lack of recovery.
 Drives can fail and all other data will continue to be accessable.
+.SS Can drives be written to directly? Outside of mergerfs while pooled?
+.PP
+Yes.
+It will be represented immediately in the pool as the policies would
+describe.
 .SS It\[aq]s mentioned that there are some security issues with mhddfs.
 What are they? How does mergerfs address them?
 .PP
@@ -858,5 +936,12 @@ email: trapexit\@spawn.link
 Gratipay: https://gratipay.com/~trapexit
 .IP \[bu] 2
 BitCoin: 12CdMhEPQVmjz3SSynkAEuD5q9JmhTDCZA
+.SH LINKS
+.IP \[bu] 2
+http://github.com/trapexit/mergerfs
+.IP \[bu] 2
+http://github.com/trapexit/mergerfs\-tools
+.IP \[bu] 2
+http://github.com/trapexit/backup\-and\-recovery\-howtos
 .SH AUTHORS
 Antonio SJ Musumeci <trapexit@spawn.link>.

src/fs.cpp

@@ -73,7 +73,8 @@ namespace fs
   bool
   info(const string &path,
        bool         &readonly,
-       size_t       &spaceavail)
+       size_t       &spaceavail,
+       size_t       &spaceused)
   {
     bool rv;
     struct statvfs st;
@@ -83,6 +84,7 @@ namespace fs
       {
         readonly   = StatVFS::readonly(st);
         spaceavail = StatVFS::spaceavail(st);
+        spaceused  = StatVFS::spaceused(st);
       }
 
     return rv;
@@ -113,6 +115,20 @@ namespace fs
     return rv;
   }
 
+  bool
+  spaceused(const string &path,
+            size_t       &spaceused)
+  {
+    bool rv;
+    struct statvfs st;
+
+    rv = fs::statvfs(path,st);
+    if(rv)
+      spaceused = StatVFS::spaceused(st);
+
+    return rv;
+  }
+
   void
   findallfiles(const vector<string> &srcmounts,
                const char           *fusepath,

src/fs.hpp

@@ -35,13 +35,17 @@ namespace fs
 
   bool info(const string &path,
             bool         &readonly,
-            size_t       &spaceavail);
+            size_t       &spaceavail,
+            size_t       &spaceused);
 
   bool readonly(const string &path);
 
   bool spaceavail(const string &path,
                   size_t       &spaceavail);
 
+  bool spaceused(const string &path,
+                 size_t       &spaceavail);
+
   void findallfiles(const vector<string> &srcmounts,
                     const char           *fusepath,
                     vector<string>       &paths);

src/fs_xattr.cpp

@@ -44,23 +44,23 @@ namespace fs
     {
 #ifndef WITHOUT_XATTR
       ssize_t rv;
-      ssize_t size;
 
       rv    = -1;
       errno = ERANGE;
-      while(rv == -1 && errno == ERANGE)
+      while((rv == -1) && (errno == ERANGE))
         {
-          size = ::flistxattr(fd,NULL,0);
-          attrs.resize(size);
-          if(size == 0)
-            return 0;
-          rv = ::flistxattr(fd,&attrs[0],size);
+          rv = ::flistxattr(fd,NULL,0);
+          if(rv <= 0)
+            return rv;
+
+          attrs.resize(rv);
+
+          rv = ::flistxattr(fd,&attrs[0],rv);
         }
 
       return rv;
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 
@@ -69,24 +69,24 @@ namespace fs
          vector<char> &attrs)
     {
 #ifndef WITHOUT_XATTR
-      int rv;
-      int size;
+      ssize_t rv;
 
       rv    = -1;
       errno = ERANGE;
-      while(rv == -1 && errno == ERANGE)
+      while((rv == -1) && (errno == ERANGE))
         {
-          size = ::listxattr(path.c_str(),NULL,0);
-          attrs.resize(size);
-          if(size == 0)
-            return 0;
-          rv = ::listxattr(path.c_str(),&attrs[0],size);
+          rv = ::llistxattr(path.c_str(),NULL,0);
+          if(rv <= 0)
+            return rv;
+
+          attrs.resize(rv);
+
+          rv = ::llistxattr(path.c_str(),&attrs[0],rv);
         }
 
       return rv;
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 
@@ -126,7 +126,7 @@ namespace fs
 
     int
     list(const int  fd,
-          string   &attrstr)
+         string    &attrstr)
     {
       int rv;
       vector<char> attrs;
@@ -158,24 +158,24 @@ namespace fs
         vector<char> &value)
     {
 #ifndef WITHOUT_XATTR
-      int rv;
-      int size;
+      ssize_t rv;
 
       rv    = -1;
       errno = ERANGE;
-      while(rv == -1 && errno == ERANGE)
+      while((rv == -1) && (errno == ERANGE))
         {
-          size = ::fgetxattr(fd,attr.c_str(),NULL,0);
-          value.resize(size);
-          if(size == 0)
-            return 0;
-          rv = ::fgetxattr(fd,attr.c_str(),&value[0],size);
+          rv = ::fgetxattr(fd,attr.c_str(),NULL,0);
+          if(rv <= 0)
+            return rv;
+
+          value.resize(rv);
+
+          rv = ::fgetxattr(fd,attr.c_str(),&value[0],rv);
         }
 
       return rv;
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 
@@ -185,24 +185,24 @@ namespace fs
         vector<char> &value)
     {
 #ifndef WITHOUT_XATTR
-      int rv;
-      int size;
+      ssize_t rv;
 
       rv    = -1;
       errno = ERANGE;
-      while(rv == -1 && errno == ERANGE)
+      while((rv == -1) && (errno == ERANGE))
         {
-          size = ::getxattr(path.c_str(),attr.c_str(),NULL,0);
-          value.resize(size);
-          if(size == 0)
-            return 0;
-          rv = ::getxattr(path.c_str(),attr.c_str(),&value[0],size);
+          rv = ::lgetxattr(path.c_str(),attr.c_str(),NULL,0);
+          if(rv <= 0)
+            return rv;
+
+          value.resize(rv);
+
+          rv = ::lgetxattr(path.c_str(),attr.c_str(),&value[0],rv);
         }
 
       return rv;
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 
@@ -305,8 +305,7 @@ namespace fs
                          value.size(),
                          flags);
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 
@@ -317,14 +316,13 @@ namespace fs
         const int     flags)
     {
 #ifndef WITHOUT_XATTR
-      return ::setxattr(path.c_str(),
-                        key.c_str(),
-                        value.data(),
-                        value.size(),
-                        flags);
+      return ::lsetxattr(path.c_str(),
+                         key.c_str(),
+                         value.data(),
+                         value.size(),
+                         flags);
 #else
-      errno = ENOTSUP;
-      return -1;
+      return (errno=ENOTSUP,-1);
 #endif
     }
 

src/policy.cpp

@@ -31,10 +31,12 @@ namespace mergerfs
     (POLICY(invalid,DOESNT_PRESERVE_PATH))
     (POLICY(all,DOESNT_PRESERVE_PATH))
     (POLICY(eplfs,PRESERVES_PATH))
+    (POLICY(eplus,PRESERVES_PATH))
     (POLICY(epmfs,PRESERVES_PATH))
     (POLICY(erofs,DOESNT_PRESERVE_PATH))
     (POLICY(ff,DOESNT_PRESERVE_PATH))
     (POLICY(lfs,DOESNT_PRESERVE_PATH))
+    (POLICY(lus,DOESNT_PRESERVE_PATH))
     (POLICY(mfs,DOESNT_PRESERVE_PATH))
     (POLICY(newest,DOESNT_PRESERVE_PATH))
     (POLICY(rand,DOESNT_PRESERVE_PATH));
@@ -46,10 +48,12 @@ namespace mergerfs
   CONST_POLICY(invalid);
   CONST_POLICY(all);
   CONST_POLICY(eplfs);
+  CONST_POLICY(eplus);
   CONST_POLICY(epmfs);
   CONST_POLICY(erofs);
   CONST_POLICY(ff);
   CONST_POLICY(lfs);
+  CONST_POLICY(lus);
   CONST_POLICY(mfs);
   CONST_POLICY(newest);
   CONST_POLICY(rand);

src/policy.hpp

@@ -44,10 +44,12 @@ namespace mergerfs
           BEGIN   = 0,
           all     = BEGIN,
           eplfs,
+          eplus,
           epmfs,
           erofs,
           ff,
           lfs,
+          lus,
           mfs,
           newest,
           rand,
@@ -96,10 +98,12 @@ namespace mergerfs
       static int invalid(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int all(CType,cstrvec&,const char*,csize_t,cstrptrvec&);
       static int eplfs(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
+      static int eplus(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int epmfs(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int erofs(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int ff(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int lfs(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
+      static int lus(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int mfs(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int newest(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
       static int rand(CType,cstrvec&,const char *,csize_t,cstrptrvec&);
@@ -167,10 +171,12 @@ namespace mergerfs
     static const Policy &invalid;
     static const Policy &all;
     static const Policy &eplfs;
+    static const Policy ⩱
     static const Policy &epmfs;
     static const Policy &erofs;
     static const Policy &ff;
     static const Policy &lfs;
+    static const Policy &lus;
     static const Policy &mfs;
     static const Policy &newest;
     static const Policy &rand;

src/policy_all.cpp

@@ -37,9 +37,10 @@ _all_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/policy_eplfs.cpp

@@ -46,13 +46,14 @@ _eplfs_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
       fs::path::make(basepath,fusepath,fullpath);
 
       if(!fs::exists(fullpath))
         continue;
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/policy_eplus.cpp

@@ -0,0 +1,146 @@
+/*
+  Copyright (c) 2016, Antonio SJ Musumeci <trapexit@spawn.link>
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted, provided that the above
+  copyright notice and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+#include <errno.h>
+
+#include <limits>
+#include <string>
+#include <vector>
+
+#include "fs.hpp"
+#include "fs_path.hpp"
+#include "policy.hpp"
+
+using std::string;
+using std::vector;
+using std::size_t;
+using mergerfs::Category;
+
+static
+int
+_eplus_create(const vector<string>  &basepaths,
+              const char            *fusepath,
+              const size_t           minfreespace,
+              vector<const string*> &paths)
+{
+  string fullpath;
+  size_t eplus;
+  const string *eplusbasepath;
+
+  eplus = std::numeric_limits<size_t>::max();
+  eplusbasepath = NULL;
+  for(size_t i = 0, ei = basepaths.size(); i != ei; i++)
+    {
+      bool readonly;
+      size_t spaceavail;
+      size_t spaceused;
+      const string *basepath = &basepaths[i];
+
+      fs::path::make(basepath,fusepath,fullpath);
+
+      if(!fs::exists(fullpath))
+        continue;
+      if(!fs::info(*basepath,readonly,spaceavail,spaceused))
+        continue;
+      if(readonly)
+        continue;
+      if(spaceavail < minfreespace)
+        continue;
+      if(spaceused >= eplus)
+        continue;
+
+      eplus = spaceused;
+      eplusbasepath = basepath;
+    }
+
+  if(eplusbasepath == NULL)
+    return POLICY_FAIL_ENOENT;
+
+  paths.push_back(eplusbasepath);
+
+  return POLICY_SUCCESS;
+}
+
+static
+int
+_eplus_other(const vector<string>  &basepaths,
+             const char            *fusepath,
+             vector<const string*> &paths)
+{
+  string fullpath;
+  size_t eplus;
+  const string *eplusbasepath;
+
+  eplus = 0;
+  eplusbasepath = NULL;
+  for(size_t i = 0, ei = basepaths.size(); i != ei; i++)
+    {
+      size_t spaceused;
+      const string *basepath = &basepaths[i];
+
+      fs::path::make(basepath,fusepath,fullpath);
+
+      if(!fs::exists(fullpath))
+        continue;
+      if(!fs::spaceused(*basepath,spaceused))
+        continue;
+      if(spaceused >= eplus)
+        continue;
+
+      eplus = spaceused;
+      eplusbasepath = basepath;
+    }
+
+  if(eplusbasepath == NULL)
+    return POLICY_FAIL_ENOENT;
+
+  paths.push_back(eplusbasepath);
+
+  return POLICY_SUCCESS;
+}
+
+static
+int
+_eplus(const Category::Enum::Type  type,
+       const vector<string>       &basepaths,
+       const char                 *fusepath,
+       const size_t                minfreespace,
+       vector<const string*>      &paths)
+{
+  if(type == Category::Enum::create)
+    return _eplus_create(basepaths,fusepath,minfreespace,paths);
+
+  return _eplus_other(basepaths,fusepath,paths);
+}
+
+namespace mergerfs
+{
+  int
+  Policy::Func::eplus(const Category::Enum::Type  type,
+                      const vector<string>       &basepaths,
+                      const char                 *fusepath,
+                      const size_t                minfreespace,
+                      vector<const string*>     &paths)
+  {
+    int rv;
+
+    rv = _eplus(type,basepaths,fusepath,minfreespace,paths);
+    if(POLICY_FAILED(rv))
+      rv = Policy::Func::lus(type,basepaths,fusepath,minfreespace,paths);
+
+    return rv;
+  }
+}

src/policy_epmfs.cpp

@@ -46,13 +46,14 @@ _epmfs_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
       fs::path::make(basepath,fusepath,fullpath);
 
       if(!fs::exists(fullpath))
         continue;
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/policy_ff.cpp

@@ -40,9 +40,10 @@ _ff_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/policy_lfs.cpp

@@ -45,9 +45,10 @@ _lfs_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/policy_lus.cpp

@@ -0,0 +1,141 @@
+/*
+  Copyright (c) 2016, Antonio SJ Musumeci <trapexit@spawn.link>
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted, provided that the above
+  copyright notice and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+#include <errno.h>
+
+#include <limits>
+#include <string>
+#include <vector>
+
+#include "fs.hpp"
+#include "fs_path.hpp"
+#include "policy.hpp"
+
+using std::string;
+using std::vector;
+using std::size_t;
+using mergerfs::Category;
+
+static
+int
+_lus_create(const vector<string>  &basepaths,
+            const size_t           minfreespace,
+            vector<const string*> &paths)
+{
+  string fullpath;
+  size_t lus;
+  const string *lusbasepath;
+
+  lus = std::numeric_limits<size_t>::max();
+  lusbasepath = NULL;
+  for(size_t i = 0, ei = basepaths.size(); i != ei; i++)
+    {
+      bool readonly;
+      size_t spaceused;
+      size_t spaceavail;
+      const string *basepath = &basepaths[i];
+
+      if(!fs::info(*basepath,readonly,spaceavail,spaceused))
+        continue;
+      if(readonly)
+        continue;
+      if(spaceavail < minfreespace)
+        continue;
+      if(spaceused >= lus)
+        continue;
+
+      lus = spaceused;
+      lusbasepath = basepath;
+    }
+
+  if(lusbasepath == NULL)
+    return POLICY_FAIL_ENOENT;
+
+  paths.push_back(lusbasepath);
+
+  return POLICY_SUCCESS;
+}
+
+static
+int
+_lus_other(const vector<string>  &basepaths,
+           const char            *fusepath,
+           vector<const string*> &paths)
+{
+  string fullpath;
+  size_t lus;
+  const string *lusbasepath;
+
+  lus = 0;
+  lusbasepath = NULL;
+  for(size_t i = 0, ei = basepaths.size(); i != ei; i++)
+    {
+      size_t spaceused;
+      const string *basepath = &basepaths[i];
+
+      fs::path::make(basepath,fusepath,fullpath);
+
+      if(!fs::exists(fullpath))
+        continue;
+      if(!fs::spaceused(*basepath,spaceused))
+        continue;
+      if(spaceused >= lus)
+        continue;
+
+      lus = spaceused;
+      lusbasepath = basepath;
+    }
+
+  if(lusbasepath == NULL)
+    return POLICY_FAIL_ENOENT;
+
+  paths.push_back(lusbasepath);
+
+  return POLICY_SUCCESS;
+}
+
+static
+int
+_lus(const Category::Enum::Type  type,
+     const vector<string>       &basepaths,
+     const char                 *fusepath,
+     const size_t                minfreespace,
+     vector<const string*>      &paths)
+{
+  if(type == Category::Enum::create)
+    return _lus_create(basepaths,minfreespace,paths);
+
+  return _lus_other(basepaths,fusepath,paths);
+}
+
+namespace mergerfs
+{
+  int
+  Policy::Func::lus(const Category::Enum::Type  type,
+                    const vector<string>       &basepaths,
+                    const char                 *fusepath,
+                    const size_t                minfreespace,
+                    vector<const string*>      &paths)
+  {
+    int rv;
+
+    rv = _lus(type,basepaths,fusepath,minfreespace,paths);
+    if(POLICY_FAILED(rv))
+      rv = Policy::Func::mfs(type,basepaths,fusepath,minfreespace,paths);
+
+    return rv;
+  }
+}

src/policy_mfs.cpp

@@ -43,9 +43,10 @@ _mfs_create(const vector<string>  &basepaths,
     {
       bool readonly;
       size_t spaceavail;
+      size_t _spaceused;
       const string *basepath = &basepaths[i];
 
-      if(!fs::info(*basepath,readonly,spaceavail))
+      if(!fs::info(*basepath,readonly,spaceavail,_spaceused))
         continue;
       if(readonly)
         continue;

src/statvfs_util.hpp

@@ -52,4 +52,12 @@ namespace StatVFS
   {
     return (st.f_frsize * st.f_bavail);
   }
+
+  static
+  inline
+  fsblkcnt_t
+  spaceused(const struct statvfs &st)
+  {
+    return (st.f_frsize * (st.f_blocks - st.f_bavail));
+  }
 }