sqfs_dir_reader_t Struct Reference

Abstracts reading of directory entries. More...

#include <dir_reader.h>

Inheritance diagram for sqfs_dir_reader_t:

Collaboration diagram for sqfs_dir_reader_t:

Public Member Functions
SQFS_API sqfs_dir_reader_t *	sqfs_dir_reader_create (const sqfs_super_t *super, sqfs_compressor_t *cmp, sqfs_file_t *file, sqfs_u32 flags)
	Create a directory reader.
SQFS_API int	sqfs_dir_reader_open_dir (sqfs_dir_reader_t *rd, const sqfs_inode_generic_t *inode, sqfs_u32 flags)
	Navigate a directory reader to the location of a directory represented by an inode.
SQFS_API int	sqfs_dir_reader_rewind (sqfs_dir_reader_t *rd)
	Reset a directory reader back to the beginning of the listing.
SQFS_API int	sqfs_dir_reader_find (sqfs_dir_reader_t *rd, const char *name)
	Seek through the current directory listing to locate an entry by name.
SQFS_API int	sqfs_dir_reader_read (sqfs_dir_reader_t *rd, sqfs_dir_entry_t **out)
	Read a directory entry and advance the internal position indicator to the next one.
SQFS_API int	sqfs_dir_reader_get_inode (sqfs_dir_reader_t *rd, sqfs_inode_generic_t **inode)
	Read the inode that the current directory entry points to.
SQFS_API int	sqfs_dir_reader_get_root_inode (sqfs_dir_reader_t *rd, sqfs_inode_generic_t **inode)
	Read the root inode using the location given by the super block.
SQFS_API int	sqfs_dir_reader_find_by_path (sqfs_dir_reader_t *rd, const sqfs_inode_generic_t *start, const char *path, sqfs_inode_generic_t **out)
	Find an inode through path traversal starting from the root or a given node downwards.
SQFS_API int	sqfs_dir_reader_get_full_hierarchy (sqfs_dir_reader_t *rd, const sqfs_id_table_t *idtbl, const char *path, sqfs_u32 flags, sqfs_tree_node_t **out)
	High level helper function for deserializing the entire file system hierarchy into an in-memory tree structure.

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 reading of directory entries.

SquashFS stores directory listings and inode structures separated from each other in meta data blocks.

The sqfs_dir_reader_t abstracts access to the filesystem tree in a SquashFS through a fairly simple interface. It keeps two meta data readers internally for reading directory listings and inodes. Externally, it offers a few simple functions for iterating over the contents of a directory that completely take care of fetching/decoding headers and sifting through the multi level hierarchie used for storing them on disk.

See sqfs_dir_writer_t for an overview on how directory entries are stored in SquashFS.

The reader also abstracts easy access to the underlying inodes, allowing direct access to the inode referred to by a directory entry.

Examples

list_files.c.

Member Function Documentation

sqfs_dir_reader_create()

SQFS_API sqfs_dir_reader_t * sqfs_dir_reader_create	(	const sqfs_super_t *	super,
		sqfs_compressor_t *	cmp,
		sqfs_file_t *	file,
		sqfs_u32	flags
	)

Create a directory reader.

The function fails if any unknown flag is set. In squashfs-tools-ng version 1.2 introduced the SQFS_DIR_READER_DOT_ENTRIES flag, earlier versions require the flags field to be set to zero.

Parameters

super	A pointer to the super block. Kept internally an used for resolving table positions.
cmp	A compressor to use for unpacking meta data blocks.
file	The input file to read from.
flags	A combination of SQFS_DIR_READER_FLAGS

Returns

A new directory reader on success, NULL on allocation failure.

sqfs_dir_reader_find()

SQFS_API int sqfs_dir_reader_find	(	sqfs_dir_reader_t *	rd,
		const char *	name
	)

Seek through the current directory listing to locate an entry by name.

Parameters

rd	A pointer to a directory reader.
name	The name of the entry to find.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_find_by_path()

SQFS_API int sqfs_dir_reader_find_by_path	(	sqfs_dir_reader_t *	rd,
		const sqfs_inode_generic_t *	start,
		const char *	path,
		sqfs_inode_generic_t **	out
	)

Find an inode through path traversal starting from the root or a given node downwards.

Parameters

rd	A pointer to a directory reader.
start	If not NULL, path traversal starts at this node downwards. If set to NULL, start at the root node.
path	A path to resolve into an inode. Forward or backward slashes can be used to separate path components. Resolving '.' or '..' is not supported.
out	Returns a pointer to a generic inode that can be freed with a single sqfs_free call.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_get_full_hierarchy()

SQFS_API int sqfs_dir_reader_get_full_hierarchy	(	sqfs_dir_reader_t *	rd,
		const sqfs_id_table_t *	idtbl,
		const char *	path,
		sqfs_u32	flags,
		sqfs_tree_node_t **	out
	)

High level helper function for deserializing the entire file system hierarchy into an in-memory tree structure.

This function internally navigates to a specified inode using sqfs_dir_reader_find_by_path and starting from that recursively deserializes the entire hierarchy into a tree structure holding all inodes.

Parameters

rd	A pointer to a directory reader.
path	A path to resolve into an inode. Forward or backward slashes can be used to separate path components. Resolving '.' or '..' is not supported. Can be set to NULL to get the root inode.
flags	A combination of SQFS_TREE_FILTER_FLAGS flags.
out	Returns the top most tree node.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_get_inode()

SQFS_API int sqfs_dir_reader_get_inode	(	sqfs_dir_reader_t *	rd,
		sqfs_inode_generic_t **	inode
	)

Read the inode that the current directory entry points to.

Parameters

rd	A pointer to a directory reader.
out	Returns a pointer to a generic inode that can be freed with a single sqfs_free call.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_get_root_inode()

SQFS_API int sqfs_dir_reader_get_root_inode	(	sqfs_dir_reader_t *	rd,
		sqfs_inode_generic_t **	inode
	)

Read the root inode using the location given by the super block.

Parameters

rd	A pointer to a directory reader.
out	Returns a pointer to a generic inode that can be freed with a single sqfs_free call.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_open_dir()

SQFS_API int sqfs_dir_reader_open_dir	(	sqfs_dir_reader_t *	rd,
		const sqfs_inode_generic_t *	inode,
		sqfs_u32	flags
	)

Navigate a directory reader to the location of a directory represented by an inode.

This function seeks to the meta data block containing the directory listing that the given inode referes to and resets the internal state. After that, consequtive cals to sqfs_dir_reader_read can be made to iterate over the directory contents.

If the reader was created with the SQFS_DIR_READER_DOT_ENTRIES flag set, the first two entries will be ".", referring to the directory inode itself and "..", referring to the parent directory inode. Those entries are generated artificially, as SquashFS does not store them on disk, hence extra work is required and a flag is used to enable this behaviour. By default, no such entries are generated.

If this flag is set, but you wish to override that behaviour on a per-instance basis, simply set the SQFS_DIR_OPEN_NO_DOT_ENTRIES flag when calling this function.

Parameters

rd	A pointer to a directory reader.
inode	An directory or extended directory inode.
flags	A combination of SQFS_DIR_OPEN_FLAGS.

Returns

Zero on success, an SQFS_ERROR value on failure.

sqfs_dir_reader_read()

SQFS_API int sqfs_dir_reader_read	(	sqfs_dir_reader_t *	rd,
		sqfs_dir_entry_t **	out
	)

Read a directory entry and advance the internal position indicator to the next one.

Call this function repeatedly to iterate over a directory listing. It returns a positive number to indicate that it couldn't fetch any more data because the end of the listing was reached. A negative value indicates an error.

After calling this function, you can use sqfs_dir_reader_get_inode to read the full inode structure that the current entry referes to.

Parameters

rd	A pointer to a directory reader.
out	Returns a pointer to a directory entry on success that can be freed with a single sqfs_free call.

Returns

Zero on success, an SQFS_ERROR value on failure, a positive number if the end of the current directory listing has been reached.

sqfs_dir_reader_rewind()

SQFS_API int sqfs_dir_reader_rewind

(

sqfs_dir_reader_t *

rd

)

Reset a directory reader back to the beginning of the listing.

Parameters

rd	A pointer to a directory reader.

Returns

Zero on success, an SQFS_ERROR value on failure.

---

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

• include/sqfs/dir_reader.h