sqfs_dir_writer_t Struct Reference

Abstracts generating of directory entries. More...

#include <dir_writer.h>

Inheritance diagram for sqfs_dir_writer_t:

Collaboration diagram for sqfs_dir_writer_t:

Public Member Functions
SQFS_API sqfs_dir_writer_t *	sqfs_dir_writer_create (sqfs_meta_writer_t *dm, sqfs_u32 flags)
	Create a directory writer.
SQFS_API int	sqfs_dir_writer_begin (sqfs_dir_writer_t *writer, sqfs_u32 flags)
	Begin writing a directory, i.e. reset and initialize all internal state neccessary.
SQFS_API int	sqfs_dir_writer_add_entry (sqfs_dir_writer_t *writer, const char *name, sqfs_u32 inode_num, sqfs_u64 inode_ref, sqfs_u16 mode)
	Add add a directory entry.
SQFS_API int	sqfs_dir_writer_end (sqfs_dir_writer_t *writer)
	Finish writing a directory listing and write everything out to the meta data writer.
SQFS_API size_t	sqfs_dir_writer_get_size (const sqfs_dir_writer_t *writer)
	Get the total, uncompressed size of the last written directory in bytes.
SQFS_API size_t	sqfs_dir_writer_get_entry_count (const sqfs_dir_writer_t *writer)
	Get the numer of entries written to the last directory.
SQFS_API sqfs_u64	sqfs_dir_writer_get_dir_reference (const sqfs_dir_writer_t *writer)
	Get the location of the last written directory.
SQFS_API size_t	sqfs_dir_writer_get_index_size (const sqfs_dir_writer_t *writer)
	Get the size of the index of the last written directory.
SQFS_API sqfs_inode_generic_t *	sqfs_dir_writer_create_inode (const sqfs_dir_writer_t *writer, size_t hlinks, sqfs_u32 xattr, sqfs_u32 parent_ino)
	Helper function for creating an inode from the last directory.
SQFS_API int	sqfs_dir_writer_write_export_table (sqfs_dir_writer_t *writer, sqfs_file_t *file, sqfs_compressor_t *cmp, sqfs_u32 root_inode_num, sqfs_u64 root_inode_ref, sqfs_super_t *super)
	Write an export table to a SquashFS image.

Additional Inherited Members
Static Public Member Functions inherited from sqfs_object_t
static SQFS_INLINE void	sqfs_destroy (void *obj)
	Destroy an object and free all its memory.
static SQFS_INLINE void *	sqfs_copy (const void *obj)
	Create a deep copy of an object if possible.
Data Fields inherited from sqfs_object_t
void(*	destroy )(struct sqfs_object_t *instance)
struct sqfs_object_t *(*	copy )(const struct sqfs_object_t *orig)

Detailed Description

Abstracts generating of directory entries.

SquashFS stores directory entries and inodes separated from each other. The inodes are stored in a series of meta data blocks before another series of meta data blocks that contain the directory entries. Directory inodes point to meta data block (and offset) where its contents are listed and the entries in turn point back to the inodes that represent them.

There are some rules to this. Directory entries have to be written in ASCIIbetical ordering. Up to 256 entries are preceeded by a header. The entries use delta encoding for inode numbers and block locations relative to the header, so every time the inodes cross a meta data block boundary, if the difference in inode number gets too large, or if the entry count would exceed 256, a new header has to be emitted. Even if the inode pointed to is an extended type, the entry in the header still has to indicate the base type.

In addtion to that, extended directory inodes can contain an index for faster lookup. The index points to each header and requires a new header to be emitted if the entries cross a block boundary.

The dir writer takes care of all of this and provides a simple interface for adding entries. Internally it fills data into a meta data writer and generates an index that it can, on request, write to another meta data writer used for inodes.

This object is not copyable, i.e. sqfs_copy will always return NULL.

Member Function Documentation

sqfs_dir_writer_add_entry()

SQFS_API int sqfs_dir_writer_add_entry	(	sqfs_dir_writer_t *	writer,
		const char *	name,
		sqfs_u32	inode_num,
		sqfs_u64	inode_ref,
		sqfs_u16	mode
	)

Add add a directory entry.

Parameters

writer	A pointer to a directory writer object.
name	The name of the directory entry.
inode_num	The inode number of the entry.
inode_ref	A reference to the inode, i.e. the meta data block offset is stored in bits 16 to 48 and the lower 16 bit hold an offset into the block.
mode	A file mode, i.e. type and permission bits from which the entry type is derived internally.

Returns

Zero on success, a SQFS_ERROR value on failure.

sqfs_dir_writer_begin()

SQFS_API int sqfs_dir_writer_begin	(	sqfs_dir_writer_t *	writer,
		sqfs_u32	flags
	)

Begin writing a directory, i.e. reset and initialize all internal state neccessary.

Parameters

writer	A pointer to a directory writer object.
flags	A currently unused flag field. Must be set to 0.

Returns

Zero on success, a SQFS_ERROR value on failure.

sqfs_dir_writer_create()

SQFS_API sqfs_dir_writer_t * sqfs_dir_writer_create	(	sqfs_meta_writer_t *	dm,
		sqfs_u32	flags
	)

Create a directory writer.

Parameters

dm	A pointer to a meta data writer that the generated directory entries should be written to.
flags	A combination of SQFS_DIR_WRITER_CREATE_FLAGS.

Returns

A pointer to a directory writer on success, NULL on allocation failure or if flags has unknown flags set.

sqfs_dir_writer_create_inode()

SQFS_API sqfs_inode_generic_t * sqfs_dir_writer_create_inode	(	const sqfs_dir_writer_t *	writer,
		size_t	hlinks,
		sqfs_u32	xattr,
		sqfs_u32	parent_ino
	)

Helper function for creating an inode from the last directory.

Call this function after sqfs_dir_writer_end to create a bare bones inode structure for the directory. The directory information is filled in completely and the type is set, the rest of the basic information such as permission bits, owner and timestamp is left untouched.

If the generated inode is an extended directory inode, you can use another convenience function called 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.

Parameters

writer	A pointer to a directory writer object.
hlinks	The number of hard links pointing to the directory.
xattr	If set to something other than 0xFFFFFFFF, an extended directory inode is created with xattr index set.
parent_ino	The inode number of the parent directory.

Returns

A generic inode or NULL on allocation failure.

sqfs_dir_writer_end()

SQFS_API int sqfs_dir_writer_end

(

sqfs_dir_writer_t *

writer

)

Finish writing a directory listing and write everything out to the meta data writer.

Parameters

writer

A pointer to a directory writer object.

Returns

Zero on success, a SQFS_ERROR value on failure.

sqfs_dir_writer_get_dir_reference()

SQFS_API sqfs_u64 sqfs_dir_writer_get_dir_reference

(

const sqfs_dir_writer_t *

writer

)

Get the location of the last written directory.

Call this function after sqfs_dir_writer_end to get the location of the directory listing that is required for the directory inodes.

Parameters

writer

A pointer to a directory writer object.

Returns

A meta data reference, i.e. bits 16 to 48 contain the block start and the lower 16 bit an offset into the uncompressed block.

sqfs_dir_writer_get_entry_count()

SQFS_API size_t sqfs_dir_writer_get_entry_count

(

const sqfs_dir_writer_t *

writer

)

Get the numer of entries written to the last directory.

Call this function after sqfs_dir_writer_end to get the total number of entries written to the directory.

Parameters

writer

A pointer to a directory writer object.

Returns

The number of entries in the directory.

sqfs_dir_writer_get_index_size()

SQFS_API size_t sqfs_dir_writer_get_index_size

(

const sqfs_dir_writer_t *

writer

)

Get the size of the index of the last written directory.

Call this function after sqfs_dir_writer_end to get the size of the directory index that is required for extended directory inodes.

Parameters

writer

A pointer to a directory writer object.

Returns

The number of index entries.

sqfs_dir_writer_get_size()

SQFS_API size_t sqfs_dir_writer_get_size

(

const sqfs_dir_writer_t *

writer

)

Get the total, uncompressed size of the last written directory in bytes.

Call this function after sqfs_dir_writer_end to get the uncompressed 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 sqfs_dir_writer_create_inode function takes this into account and adds the 3 internally.

Parameters

writer

A pointer to a directory writer object.

Returns

The size of the entire, uncompressed listing in bytes.

sqfs_dir_writer_write_export_table()

SQFS_API int sqfs_dir_writer_write_export_table	(	sqfs_dir_writer_t *	writer,
		sqfs_file_t *	file,
		sqfs_compressor_t *	cmp,
		sqfs_u32	root_inode_num,
		sqfs_u64	root_inode_ref,
		sqfs_super_t *	super
	)

Write an export table to a SquashFS image.

If the sqfs_dir_writer_t was created with the SQFS_DIR_WRITER_CREATE_EXPORT_TABLE flag set, it has an internal table that maps all inode numbers to inode references. After writing the fragment table, this function can be used to write this inode mapping table for NFS export support.

It is safe to call this function if the writer has been created without the flag. In this case, it is simply a noop.

In theory, the writer "sees" the entire directory tree and for each entry, the inode number and on-disk location, so it can build this table. The only inode it never sees is the root inode, so that information has to be passed to this function to add it to the table just before writing it to disk.

Parameters

writer	A pointer to a directory writer object.
file	The ouput file to write the table to.
cmp	The compressor to use to compress the table.
root_inode_num	The inode number of the root inode.
root_inode_ref	An inode reference for the root inode.
super	A pointer to the super block. Location of the export table and the exportable flag are set.

Returns

Zero on success, a SQFS_ERROR value on failure.

---

The documentation for this struct was generated from the following file:

• include/sqfs/dir_writer.h