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 8ed555e..d4fb229 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -77,9 +77,16 @@
/** 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 @@
/**
* 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.
*
- * 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.
+ * 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.
*
- * The filesystem may ignore forget calls, if the inodes don't
- * need to have a limited lifetime.
+ * 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.
*
- * On unmount it is not guaranteed, that all referenced inodes
- * will receive a forget message.
+ * 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 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 @@
/**
* 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 @@
/**
* 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
*
@@ -346,6 +376,12 @@
/** 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 @@
/**
* Forget about multiple inodes
*
+ * See description of the forget function for more
+ * information.
+ *
* Introduced in version 2.9
*
* Valid replies:
@@ -1021,6 +1060,9 @@
* 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 @@
* Possible requests:
* create
*
+ * Side effects:
+ * increments the lookup count on success
+ *
* @param req request handle
* @param e the entry parameters
* @param fi file information