From e081e64490923b08c440ba001747c933007c4602 Mon Sep 17 00:00:00 2001
From: Nikolaus Rath <Nikolaus@rath.org>
Date: Wed, 7 Dec 2011 10:15:36 -0500
Subject: fuse: documentation update for forget

Update documentation for forget and related methods
---
 include/fuse_lowlevel.h | 69 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 57 insertions(+), 12 deletions(-)

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 @@ 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
-- 
cgit v1.2.3