Document meaning of zero telldir() offset.

diff --git a/ChangeLog.rst b/ChangeLog.rst
index 844f6620246086d4ea6e16bf796043d093efb070..a724709b6de4c4069fb48071ca7f9923b422a952 100644 (file)
--- 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 25457f1dd6fba0418060f9003b0b45c0c7853ef5..5eb257c7bc43054c903b126d1cf6b3ac93a1c9b6 100644 (file)
--- 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 efe4edbb1ffb4cb40d7413be73199fb8dc658b9a..cd045f32f58d3eaa63655c7ed855174d5a8ed3ee 100644 (file)
--- 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