fuse: documentation update for forget

Update documentation for forget and related methods

diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index 8ed555eb629911161ff84d36c43f9e281fb0424e..d4fb229d50727f85f0df880bf0ba056e58ef0aca 100644 (file)
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -77,9 +77,16 @@ struct fuse_entry_param {
 
        /** Generation number for this entry.
         *
-        * The ino/generation pair should be unique for the filesystem's
-        * lifetime. It must be non-zero, otherwise FUSE will treat it as an
-        * error.
+        * If the file system will be exported over NFS, the
+        * ino/generation pairs need to be unique over the file
+        * system's lifetime (rather than just the mount time). So if
+        * the file system reuses an inode after it has been deleted,
+        * it must assign a new, previously unused generation number
+        * to the inode at the same time.
+        *
+        * The generation must be non-zero, otherwise FUSE will treat
+        * it as an error.
+        *
         */
        unsigned long generation;
 
@@ -193,18 +200,31 @@ struct fuse_lowlevel_ops {
        /**
         * Forget about an inode
         *
-        * The nlookup parameter indicates the number of lookups
-        * previously performed on this inode.
+        * This function is called when the kernel removes an inode
+        * from its internal caches.
+        *
+        * The inode's lookup count increases by one for every call to
+        * fuse_reply_entry and fuse_reply_create. The nlookup parameter
+        * indicates by how much the lookup count should be decreased.
         *
-        * If the filesystem implements inode lifetimes, it is recommended
-        * that inodes acquire a single reference on each lookup, and lose
-        * nlookup references on each forget.
+        * Inodes with a non-zero lookup count may receive request from
+        * the kernel even after calls to unlink, rmdir or (when
+        * overwriting an existing file) rename. Filesystems must handle
+        * such requests properly and it is recommended to defer removal
+        * of the inode until the lookup count reaches zero. Calls to
+        * unlink, remdir or rename will be followed closely by forget
+        * unless the file or directory is open, in which case the
+        * kernel issues forget only after the release or releasedir
+        * calls.
         *
-        * The filesystem may ignore forget calls, if the inodes don't
-        * need to have a limited lifetime.
+        * Note that if a file system will be exported over NFS the
+        * inodes lifetime must extend even beyond forget. See the
+        * generation field in struct fuse_entry_param above.
         *
-        * On unmount it is not guaranteed, that all referenced inodes
-        * will receive a forget message.
+        * On unmount the lookup count for all inodes implicitly drops
+        * to zero. It is not guaranteed that the file system will
+        * receive corresponding forget messages for the affected
+        * inodes.
         *
         * Valid replies:
         *   fuse_reply_none
@@ -308,6 +328,11 @@ struct fuse_lowlevel_ops {
        /**
         * Remove a file
         *
+        * If the file's inode's lookup count is non-zero, the file
+        * system is expected to postpone any removal of the inode
+        * until the lookup count reaches zero (see description of the
+        * forget function).
+        *
         * Valid replies:
         *   fuse_reply_err
         *
@@ -320,6 +345,11 @@ struct fuse_lowlevel_ops {
        /**
         * Remove a directory
         *
+        * If the directory's inode's lookup count is non-zero, the
+        * file system is expected to postpone any removal of the
+        * inode until the lookup count reaches zero (see description
+        * of the forget function).
+        *
         * Valid replies:
         *   fuse_reply_err
         *
@@ -345,6 +375,12 @@ struct fuse_lowlevel_ops {
                         const char *name);
 
        /** Rename a file
+        *
+        * If the target exists it should be atomically replaced. If
+        * the target's inode's lookup count is non-zero, the file
+        * system is expected to postpone any removal of the inode
+        * until the lookup count reaches zero (see description of the
+        * forget function).
         *
         * Valid replies:
         *   fuse_reply_err
@@ -928,6 +964,9 @@ struct fuse_lowlevel_ops {
        /**
         * Forget about multiple inodes
         *
+        * See description of the forget function for more
+        * information.
+        *
         * Introduced in version 2.9
         *
         * Valid replies:
@@ -1021,6 +1060,9 @@ void fuse_reply_none(fuse_req_t req);
  * Possible requests:
  *   lookup, mknod, mkdir, symlink, link
  *
+ * Side effects:
+ *   increments the lookup count on success
+ *
  * @param req request handle
  * @param e the entry parameters
  * @return zero for success, -errno for failure to send reply
@@ -1036,6 +1078,9 @@ int fuse_reply_entry(fuse_req_t req, const struct fuse_entry_param *e);
  * Possible requests:
  *   create
  *
+ * Side effects:
+ *   increments the lookup count on success
+ *
  * @param req request handle
  * @param e the entry parameters
  * @param fi file information