Merge pull request #491 from trapexit/inode_docs

add details regarding use_ino

README.md

@@ -1,6 +1,6 @@
 % mergerfs(1) mergerfs user manual
 % Antonio SJ Musumeci <trapexit@spawn.link>
-% 2018-03-09
+% 2018-07-25
 
 # NAME
 
@@ -694,6 +694,21 @@ mergerfs-inode = (original-inode | (device-id << 32))
 
 While `ino_t` is 64 bits only a few filesystems use more than 32. Similarly, while `dev_t` is also 64 bits it was traditionally 16 bits. Bitwise or'ing them together should work most of the time. While totally unique inodes are preferred the overhead which would be needed does not seem to outweighted by the benefits.
 
+While atypical, yes, inodes can be reused and not refer to the same file. The internal id used to reference a file in FUSE is different from the inode value presented. The former is the `nodeid` and is actually a tuple of (nodeid,generation). That tuple is not user facing. The inode is merely metadata passed through the kernel and found using the `stat` family of calls or `readdir`.
+
+From FUSE docs regarding `use_ino`:
+
+```
+Honor the st_ino field in the functions getattr() and
+fill_dir(). This value is used to fill in the st_ino field
+in the stat(2), lstat(2), fstat(2) functions and the d_ino
+field in the readdir(2) function. The filesystem does not
+have to guarantee uniqueness, however some applications
+rely on this value being unique for the whole filesystem.
+Note that this does *not* affect the inode that libfuse
+and the kernel use internally (also called the "nodeid").
+```
+
 #### 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) manages running 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 behavior the proper way to manage this is to use [seteuid](http://linux.die.net/man/2/seteuid) and [setegid](http://linux.die.net/man/2/setegid), in effect becoming the user making the original call, and perform the action as them. This is what mergerfs does.

man/mergerfs.1

@@ -1,7 +1,7 @@
 .\"t
 .\" Automatically generated by Pandoc 1.19.2.4
 .\"
-.TH "mergerfs" "1" "2018\-03\-09" "mergerfs user manual" ""
+.TH "mergerfs" "1" "2018\-07\-25" "mergerfs user manual" ""
 .hy
 .SH NAME
 .PP
@@ -1476,6 +1476,31 @@ bits.
 Bitwise or\[aq]ing them together should work most of the time.
 While totally unique inodes are preferred the overhead which would be
 needed does not seem to outweighted by the benefits.
+.PP
+While atypical, yes, inodes can be reused and not refer to the same
+file.
+The internal id used to reference a file in FUSE is different from the
+inode value presented.
+The former is the \f[C]nodeid\f[] and is actually a tuple of
+(nodeid,generation).
+That tuple is not user facing.
+The inode is merely metadata passed through the kernel and found using
+the \f[C]stat\f[] family of calls or \f[C]readdir\f[].
+.PP
+From FUSE docs regarding \f[C]use_ino\f[]:
+.IP
+.nf
+\f[C]
+Honor\ the\ st_ino\ field\ in\ the\ functions\ getattr()\ and
+fill_dir().\ This\ value\ is\ used\ to\ fill\ in\ the\ st_ino\ field
+in\ the\ stat(2),\ lstat(2),\ fstat(2)\ functions\ and\ the\ d_ino
+field\ in\ the\ readdir(2)\ function.\ The\ filesystem\ does\ not
+have\ to\ guarantee\ uniqueness,\ however\ some\ applications
+rely\ on\ this\ value\ being\ unique\ for\ the\ whole\ filesystem.
+Note\ that\ this\ does\ *not*\ affect\ the\ inode\ that\ libfuse
+and\ the\ kernel\ use\ internally\ (also\ called\ the\ "nodeid").
+\f[]
+.fi
 .SS It\[aq]s mentioned that there are some security issues with mhddfs.
 What are they? How does mergerfs address them?
 .PP