From 1a73904e687b588bf669fa702d823b092ab9eb0c Mon Sep 17 00:00:00 2001
From: Nikolaus Rath <Nikolaus@rath.org>
Date: Tue, 22 Aug 2017 13:45:41 +0200
Subject: Document meaning of zero telldir() offset.

---
 ChangeLog.rst           |  3 +++
 include/fuse.h          |  6 ++++++
 include/fuse_lowlevel.h | 22 +++++++---------------
 3 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/ChangeLog.rst b/ChangeLog.rst
index 844f662..a724709 100644
--- a/ChangeLog.rst
+++ b/ChangeLog.rst
@@ -1,6 +1,9 @@
 Unreleased Changes
 ==================
 
+* Documented the special meaning of the *zero* offset for the
+  fuse_fill_dir_t function.
+  
 * libfuse can now be build without libiconv.
 
 * Fixed support for `FUSE_CAP_POSIX_ACL`: setting this capability
diff --git a/include/fuse.h b/include/fuse.h
index 25457f1..5eb257c 100644
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -66,6 +66,12 @@ enum fuse_fill_dir_flags {
 
 /** Function to add an entry in a readdir() operation
  *
+ * The *off* parameter can be any non-zero value that enableds the
+ * filesystem to identify the current point in the directory
+ * stream. It does not need to be the actual physical position. A
+ * value of zero is reserved to indicate that seeking in directories
+ * is not supported.
+ * 
  * @param buf the buffer passed to the readdir() operation
  * @param name the file name of the directory entry
  * @param stat file attributes, can be NULL
diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index efe4edb..cd045f3 100644
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -1421,9 +1421,12 @@ int fuse_reply_bmap(fuse_req_t req, uint64_t idx);
  * From the 'stbuf' argument the st_ino field and bits 12-15 of the
  * st_mode field are used.  The other fields are ignored.
  *
- * Note: offsets do not necessarily represent physical offsets, and
- * could be any marker, that enables the implementation to find a
- * specific point in the directory stream.
+ * *off* should be any non-zero value that the filesystem can use to
+ * identify the current point in the directory stream. It does not
+ * need to be the actual physical position. A value of zero is
+ * reserved to mean "from the beginning", and should therefore never
+ * be used (the first call to fuse_add_direntry should be passed the
+ * offset of the second directory entry).
  *
  * @param req request handle
  * @param buf the point where the new entry will be added to the buffer
@@ -1440,18 +1443,7 @@ size_t fuse_add_direntry(fuse_req_t req, char *buf, size_t bufsize,
 /**
  * Add a directory entry to the buffer with the attributes
  *
- * Buffer needs to be large enough to hold the entry.  If it's not,
- * then the entry is not filled in but the size of the entry is still
- * returned.  The caller can check this by comparing the bufsize
- * parameter with the returned entry size.  If the entry size is
- * larger than the buffer size, the operation failed.
- *
- * From the 'stbuf' argument the st_ino field and bits 12-15 of the
- * st_mode field are used.  The other fields are ignored.
- *
- * Note: offsets do not necessarily represent physical offsets, and
- * could be any marker, that enables the implementation to find a
- * specific point in the directory stream.
+ * See documentation of `fuse_add_direntryt()` for more details.
  *
  * @param req request handle
  * @param buf the point where the new entry will be added to the buffer
-- 
cgit v1.2.3