Improve readdir() and file handle documentation

Fixes: #333 

1 files changed, 22 insertions, 11 deletions

diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 7922d67..ae6736e 100644
--- 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.