Improve readdir() and file handle documentation

Fixes: #333

diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 7922d672ac1739bd161c2d9be15d88b50e70cfe8..ae6736eb66b8451dd2c4c87e0fcc99a6de8133b8 100644 (file)
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -496,8 +496,8 @@ struct fuse_lowlevel_ops {
         * If this request is answered with an error code of ENOSYS
         * and FUSE_CAP_NO_OPEN_SUPPORT is set in
         * `fuse_conn_info.capable`, this is treated as success and
-        * future calls to open will also succeed without being send
-        * to the filesystem process.
+        * future calls to open and release will also succeed without being
+        * sent to the filesystem process.
         *
         * Valid replies:
         *   fuse_reply_open
@@ -611,7 +611,8 @@ struct fuse_lowlevel_ops {
         * file: all file descriptors are closed and all memory mappings
         * are unmapped.
         *
-        * For every open call there will be exactly one release call.
+        * For every open call there will be exactly one release call (unless
+        * the filesystem is force-unmounted).
         *
         * The filesystem may reply with an error, but error values are
         * not returned to close() or munmap() which triggered the
@@ -660,12 +661,6 @@ struct fuse_lowlevel_ops {
         * etc) in fi->fh, and use this in other all other directory
         * stream operations (readdir, releasedir, fsyncdir).
         *
-        * Filesystem may also implement stateless directory I/O and not
-        * store anything in fi->fh, though that makes it impossible to
-        * implement standard conforming directory stream operations in
-        * case the contents of the directory can change between opendir
-        * and releasedir.
-        *
         * Valid replies:
         *   fuse_reply_open
         *   fuse_reply_err
@@ -690,8 +685,24 @@ struct fuse_lowlevel_ops {
         * Returning a directory entry from readdir() does not affect
         * its lookup count.
         *
+         * If off_t is non-zero, then it will correspond to one of the off_t
+        * values that was previously returned by readdir() for the same
+        * directory handle. In this case, readdir() should skip over entries
+        * coming before the position defined by the off_t value. If entries
+        * are added or removed while the directory handle is open, they filesystem
+        * may still include the entries that have been removed, and may not
+        * report the entries that have been created. However, addition or
+        * removal of entries must never cause readdir() to skip over unrelated
+        * entries or to report them more than once. This means
+        * that off_t can not be a simple index that enumerates the entries
+        * that have been returned but must contain sufficient information to
+        * uniquely determine the next directory entry to return even when the
+        * set of entries is changing.
+        *
         * The function does not have to report the '.' and '..'
-        * entries, but is allowed to do so.
+        * entries, but is allowed to do so. Note that, if readdir does
+        * not return '.' or '..', they will not be implicitly returned,
+        * and this behavior is observable by the caller.
         *
         * Valid replies:
         *   fuse_reply_buf
@@ -711,7 +722,7 @@ struct fuse_lowlevel_ops {
         * Release an open directory
         *
         * For every opendir call there will be exactly one releasedir
-        * call.
+        * call (unless the filesystem is force-unmounted).
         *
         * fi->fh will contain the value set by the opendir method, or
         * will be undefined if the opendir method didn't set any value.