From fd0ed8290ece2e219508b62d90a00fcdf794d406 Mon Sep 17 00:00:00 2001 From: Chad Austin Date: Sat, 9 Mar 2019 03:02:24 -0800 Subject: [PATCH] Improve readdir() and file handle documentation Fixes: #333 --- include/fuse_lowlevel.h | 33 ++++++++++++++++++++++----------- 1 file 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. -- 2.30.2