summaryrefslogtreecommitdiff
path: root/include/sqfs/super.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/sqfs/super.h')
-rw-r--r--include/sqfs/super.h231
1 files changed, 228 insertions, 3 deletions
diff --git a/include/sqfs/super.h b/include/sqfs/super.h
index 4556d3d..5e6c00a 100644
--- a/include/sqfs/super.h
+++ b/include/sqfs/super.h
@@ -22,34 +22,172 @@
#include "sqfs/predef.h"
+/**
+ * @file super.h
+ *
+ * @brief Contains on-disk data structures, identifiers and functions for the
+ * SquashFS super block.
+ */
+
#define SQFS_MAGIC 0x73717368
#define SQFS_VERSION_MAJOR 4
#define SQFS_VERSION_MINOR 0
#define SQFS_DEVBLK_SIZE 4096
#define SQFS_DEFAULT_BLOCK_SIZE 131072
+/**
+ * @struct sqfs_super_t
+ *
+ * @brief The SquashFS super block, located at the beginning of the file system
+ * to describe the layout of the filesystem.
+ */
struct sqfs_super_t {
+ /**
+ * @brief Magic number. Must be set to SQFS_MAGIC.
+ */
uint32_t magic;
+
+ /**
+ * @brief Total number of inodes.
+ */
uint32_t inode_count;
+
+ /**
+ * @brief Last time the filesystem was modified.
+ *
+ * This field counts seconds (not counting leap seconds) since 00:00,
+ * Jan 1 1970 UTC. This field is unsigned, so it expires in the year
+ * 2106 (as opposed to 2038).
+ */
uint32_t modification_time;
+
+ /**
+ * @brief The data block size in bytes.
+ *
+ * Must be a power of 2, no less than 4k and not larger than 1M.
+ */
uint32_t block_size;
+
+ /**
+ * @brief The number of fragment blocks in the data area.
+ */
uint32_t fragment_entry_count;
+
+ /**
+ * @brief Identifies the compressor that has been used.
+ *
+ * Valid identifiers are in the @ref E_SQFS_COMPRESSOR enum.
+ */
uint16_t compression_id;
+
+ /**
+ * @brief The log2 of the block_size field for sanity checking
+ *
+ * Must be no less than 12 and not larger than 20.
+ */
uint16_t block_log;
+
+ /**
+ * @brief A combination of @ref E_SQFS_SUPER_FLAGS flags
+ *
+ * Most of the flags that can be set here are informative only.
+ */
uint16_t flags;
+
+ /**
+ * @brief The total number of unique user or group IDs.
+ */
uint16_t id_count;
+
+ /**
+ * @brief Must be @ref SQFS_VERSION_MAJOR
+ */
uint16_t version_major;
+
+ /**
+ * @brief Must be @ref SQFS_VERSION_MINOR
+ */
uint16_t version_minor;
+
+ /**
+ * @brief A reference to the root inode
+ *
+ * The bits 16 to 48 hold an offset that is added to inode_table_start
+ * to get the location of the meta data block containing the inode.
+ * The lower 16 bits hold a byte offset into the uncompressed block.
+ */
uint64_t root_inode_ref;
+
+ /**
+ * @brief Total size of the file system in bytes, not counting padding
+ */
uint64_t bytes_used;
+
+ /**
+ * @brief On-disk location of the ID table
+ *
+ * This value must point to a location after the directory table and
+ * (if present) after the export and fragment tables, but before the
+ * xattr table.
+ */
uint64_t id_table_start;
+
+ /**
+ * @brief On-disk location of the extended attribute table (if present)
+ *
+ * See @ref sqfs_xattr_reader_t for an overview on how SquashFS stores
+ * extended attributes on disk.
+ *
+ * This value must either point to a location after the ID table, or
+ * it must be set to 0xFFFFFFFF to indicate the table is not present.
+ */
uint64_t xattr_id_table_start;
+
+ /**
+ * @brief On-disk location of the first meta data block containing
+ * the inodes
+ *
+ * This value must point to a location before the directory table.
+ */
uint64_t inode_table_start;
+
+ /**
+ * @brief On-disk location of the first meta data block containing
+ * the directory entries
+ *
+ * This value must point to a location after the inode table but
+ * before the fragment, export, ID and xattr tables.
+ */
uint64_t directory_table_start;
+
+ /**
+ * @brief On-disk location of the fragment table (if present)
+ *
+ * This value must either point to a location after the directory
+ * table, but before the export, ID and xattr tables, or it must be
+ * set to 0xFFFFFFFF to indicate that the table is not present.
+ */
uint64_t fragment_table_start;
+
+ /**
+ * @brief On-disk location of the export table (if present)
+ *
+ * This value must either point to a location after directory table
+ * (and if present after the fragment table), but before the ID table,
+ * or it must be set to 0xFFFFFFFF to indicate that the table is not
+ * present.
+ */
uint64_t export_table_start;
};
+/**
+ * @enum E_SQFS_COMPRESSOR
+ *
+ * @brief Set in @ref sqfs_super_t to identify the compresser used by the
+ * filesystem.
+ *
+ * Most of the flags that can be set are informative only.
+ */
typedef enum {
SQFS_COMP_GZIP = 1,
SQFS_COMP_LZMA = 2,
@@ -62,17 +200,72 @@ typedef enum {
SQFS_COMP_MAX = 6,
} E_SQFS_COMPRESSOR;
+/**
+ * @enum E_SQFS_SUPER_FLAGS
+ *
+ * @brief Flags that can be set in @ref sqfs_super flags field.
+ */
typedef enum {
+ /**
+ * @brief Set to indicate that meta data blocks holding the inodes are
+ * stored uncompressed.
+ */
SQFS_FLAG_UNCOMPRESSED_INODES = 0x0001,
+
+ /**
+ * @brief Set to indicate that all data blocks are stored uncompressed.
+ */
SQFS_FLAG_UNCOMPRESSED_DATA = 0x0002,
+
+ /**
+ * @brief Set to indicate that all fragment blocks are stored
+ * uncompressed.
+ */
SQFS_FLAG_UNCOMPRESSED_FRAGMENTS = 0x0008,
+
+ /**
+ * @brief Set to indicate that there are no fragment blocks.
+ */
SQFS_FLAG_NO_FRAGMENTS = 0x0010,
+
+ /**
+ * @brief Set to indicate that fragments have been generated for all
+ * files that are not a multiple of the block size in size.
+ */
SQFS_FLAG_ALWAYS_FRAGMENTS = 0x0020,
+
+ /**
+ * @brief Set to indicate that data blocks have not been deduplicated.
+ */
SQFS_FLAG_DUPLICATES = 0x0040,
+
+ /**
+ * @brief Set to indicate that an NFS export table is present.
+ */
SQFS_FLAG_EXPORTABLE = 0x0080,
+
+ /**
+ * @brief Set to indicate that meta data blocks holding extended
+ * attributes are stored uncompressed.
+ */
SQFS_FLAG_UNCOMPRESSED_XATTRS = 0x0100,
+
+ /**
+ * @brief Set to indicate that the filesystem does not
+ * contain extended attributes.
+ */
SQFS_FLAG_NO_XATTRS = 0x0200,
+
+ /**
+ * @brief Set to indicate that a single, uncompressed meta data block
+ * with compressor options follows the super block.
+ */
SQFS_FLAG_COMPRESSOR_OPTIONS = 0x0400,
+
+ /**
+ * @brief Set to indicate that meta data blocks holding the IDs are
+ * stored uncompressed.
+ */
SQFS_FLAG_UNCOMPRESSED_IDS = 0x0800,
} E_SQFS_SUPER_FLAGS;
@@ -80,15 +273,47 @@ typedef enum {
extern "C" {
#endif
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Initialize the SquashFS super block.
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to a super block structure.
+ * @param block_size The uncompressed size of the data blocks in bytes.
+ * @param mtime The modification time stamp to set.
+ * @param compressor The compressor ID to set.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ * fields does not hold a valid value.
+ */
SQFS_API int sqfs_super_init(sqfs_super_t *super, size_t block_size,
uint32_t mtime,
E_SQFS_COMPRESSOR compressor);
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Encode and write a SquashFS super block to disk.
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to the super block structure to write.
+ * @param file A file object through which to access the filesystem image.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ * fields does not hold a valid value.
+ */
SQFS_API int sqfs_super_write(sqfs_super_t *super, sqfs_file_t *file);
-/* Returns 0 on success. Prints error messages to stderr on failure. */
+/**
+ * @brief Read a SquashFS super block from disk, decode it and check the fields
+ *
+ * @memberof sqfs_super_t
+ *
+ * @param super A pointer to the super block structure to fill.
+ * @param file A file object through which to access the filesystem image.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value if one of the
+ * fields does not hold a valid value.
+ */
SQFS_API int sqfs_super_read(sqfs_super_t *super, sqfs_file_t *file);
#ifdef __cplusplus