summaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
Diffstat (limited to 'include')
-rw-r--r--include/sqfs/dir_writer.h7
-rw-r--r--include/sqfs/inode.h11
2 files changed, 17 insertions, 1 deletions
diff --git a/include/sqfs/dir_writer.h b/include/sqfs/dir_writer.h
index 9615a41..7b35fe0 100644
--- a/include/sqfs/dir_writer.h
+++ b/include/sqfs/dir_writer.h
@@ -161,6 +161,11 @@ SQFS_API int sqfs_dir_writer_end(sqfs_dir_writer_t *writer);
* size of the directory listing that is required for the directory inodes.
* And also to determine which kind of directory inode to create.
*
+ * Note that this size is only what was written to disk. SquashFS directory
+ * inodes need you to add 3 to this value, to account for "." and ".." entries
+ * which are not actually stored on disk. The @ref sqfs_dir_writer_create_inode
+ * function takes this into account and adds the 3 internally.
+ *
* @param writer A pointer to a directory writer object.
*
* @return The size of the entire, uncompressed listing in bytes.
@@ -226,6 +231,8 @@ SQFS_API size_t sqfs_dir_writer_get_index_size(const sqfs_dir_writer_t *writer);
* convenience function called @ref sqfs_dir_writer_write_index to write the
* index meta data after writing the inode itself.
*
+ * @note The size is already adjusted for the required off-by-3 value.
+ *
* @param writer A pointer to a directory writer object.
* @param hlinks The number of hard links pointing to the directory.
* @param xattr If set to something other than 0xFFFFFFFF, an extended
diff --git a/include/sqfs/inode.h b/include/sqfs/inode.h
index 0bc33db..8df7158 100644
--- a/include/sqfs/inode.h
+++ b/include/sqfs/inode.h
@@ -400,6 +400,15 @@ struct sqfs_inode_dir_t {
/**
* @brief Combined size of all directory entries and headers in bytes.
+ *
+ * The value stored here is off by 3 bytes, i.e. 3 bytes larger than
+ * the actual listing on disk. The Linux implementation of SquashFS
+ * uses readdir() offsets 0 and 1 to synthesize "." and ".." entries,
+ * and after that looks into the actual directory.
+ *
+ * Why store an off-by-3 value on disk instead of faking it in the
+ * kernel and have something consistent here? Beats me, but that's
+ * how it is implemented.
*/
sqfs_u16 size;
@@ -428,7 +437,7 @@ struct sqfs_inode_dir_ext_t {
sqfs_u32 nlink;
/**
- * @brief Combined size of all directory entries and headers in bytes.
+ * @brief Size of all directory entries and headers in bytes plus 3.
*/
sqfs_u32 size;