sqfs_xattr_reader_t Struct Reference

Abstracts read access to extended attributes in a SquashFS filesystem. More...

#include <xattr_reader.h>

Inheritance diagram for sqfs_xattr_reader_t:

Collaboration diagram for sqfs_xattr_reader_t:

Public Member Functions
SQFS_API sqfs_xattr_reader_t *	sqfs_xattr_reader_create (sqfs_u32 flags)
	Create an xattr reader.
SQFS_API int	sqfs_xattr_reader_load (sqfs_xattr_reader_t *xr, const sqfs_super_t *super, sqfs_file_t *file, sqfs_compressor_t *cmp)
	Load the locations of the xattr meta data blocks into memory.
SQFS_API int	sqfs_xattr_reader_get_desc (sqfs_xattr_reader_t *xr, sqfs_u32 idx, sqfs_xattr_id_t *desc)
	Resolve an xattr index from an inode to an xattr description.
SQFS_API int	sqfs_xattr_reader_seek_kv (sqfs_xattr_reader_t *xr, const sqfs_xattr_id_t *desc)
	Resolve an xattr index from an inode to an xattr description.
SQFS_API int	sqfs_xattr_reader_read_key (sqfs_xattr_reader_t *xr, sqfs_xattr_entry_t **key_out)
	Read the next xattr key.
SQFS_API int	sqfs_xattr_reader_read_value (sqfs_xattr_reader_t *xr, const sqfs_xattr_entry_t *key, sqfs_xattr_value_t **val_out)
	Read the xattr value belonging to the last read key.

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 read access to extended attributes in a SquashFS filesystem.

SquashFS stores extended attributes using multiple levels of indirection. First of all, the key-value pairs of each inode (that has extended attributes) are deduplicated and stored consecutively in meta data blocks. Furthermore, a value can be stored out-of-band, i.e. it holds a reference to another location from which the value has to be read.

For each unique set of key-value pairs, a descriptor object is generated that holds the location of the first pair, the number of pairs and the total size used on disk. The array of descriptor objects is stored in multiple meta data blocks. Each inode that has extended attributes holds a 32 bit index into the descriptor array.

The third layer of indirection is yet another table that points to the locations of the previous two tables. Its location is in turn stored in the super block.

The sqfs_xattr_reader_t data structure takes care of the low level details of loading and parsing the data.

After creating an instance using sqfs_xattr_reader_create, simply call sqfs_xattr_reader_load_locations to load and parse all of the location tables. Then use sqfs_xattr_reader_get_desc to resolve a 32 bit index from an inode to a descriptor structure. Use sqfs_xattr_reader_seek_kv to point the reader to the start of the key-value pairs and the call sqfs_xattr_reader_read_key and sqfs_xattr_reader_read_value consecutively to read and decode each key-value pair.

Member Function Documentation

sqfs_xattr_reader_create()

SQFS_API sqfs_xattr_reader_t * sqfs_xattr_reader_create

(

sqfs_u32

flags

)

Create an xattr reader.

This function creates an object that abstracts away read only access to the extended attributes in a SquashFS filesystem.

After creating a reader and before using it, call sqfs_xattr_reader_load_locations to load and parse the location information required to look up xattr key-value pairs.

All pointers passed to this function are stored internally for later use. Do not destroy any of the pointed to objects before destroying the xattr reader.

Parameters

flags

Currently must be set to 0, or creation will fail.

Returns

A pointer to a new xattr reader instance on success, NULL on allocation failure.

sqfs_xattr_reader_get_desc()

SQFS_API int sqfs_xattr_reader_get_desc	(	sqfs_xattr_reader_t *	xr,
		sqfs_u32	idx,
		sqfs_xattr_id_t *	desc
	)

Resolve an xattr index from an inode to an xattr description.

This function takes an xattr index from an extended inode type and resolves it to a descriptor that points to location of the key-value pairs and indicates how many key-value pairs to read from there.

Parameters

xr	A pointer to an xattr reader instance
idx	The xattr index to resolve
desc	Used to return the description

Returns

Zero on success, a negative SQFS_ERROR value on failure.

sqfs_xattr_reader_load()

SQFS_API int sqfs_xattr_reader_load	(	sqfs_xattr_reader_t *	xr,
		const sqfs_super_t *	super,
		sqfs_file_t *	file,
		sqfs_compressor_t *	cmp
	)

Load the locations of the xattr meta data blocks into memory.

This function must be called explicitly after an xattr reader has been created to load the actual location table from disk.

Parameters

xr	A pointer to an xattr reader instance.
super	A pointer to the SquashFS super block required to find the location tables.
file	A pointer to a file object that contains the SquashFS filesystem.
cmp	A pointer to a compressor used to uncompress the loaded meta data blocks.

Returns

Zero on success, a negative SQFS_ERROR value on failure.

sqfs_xattr_reader_read_key()

SQFS_API int sqfs_xattr_reader_read_key	(	sqfs_xattr_reader_t *	xr,
		sqfs_xattr_entry_t **	key_out
	)

Read the next xattr key.

After setting the start position using sqfs_xattr_reader_seek_kv, this function reads and decodes an xattr key and advances the internal position indicator to the location after the key. The value can then be read using using sqfs_xattr_reader_read_value. After reading the value, the next key can be read by calling this function again.

Parameters

xr	A pointer to an xattr reader instance
key_out	Used to return the decoded key. The underlying memory can be released using a single sqfs_free call.

Returns

Zero on success, a negative SQFS_ERROR value on failure.

sqfs_xattr_reader_read_value()

SQFS_API int sqfs_xattr_reader_read_value	(	sqfs_xattr_reader_t *	xr,
		const sqfs_xattr_entry_t *	key,
		sqfs_xattr_value_t **	val_out
	)

Read the xattr value belonging to the last read key.

After calling sqfs_xattr_reader_read_key, this function can read and decode the asociated value. The internal location indicator is then advanced past the key to the next value, so sqfs_xattr_reader_read_key can be called again to read the next key.

Parameters

xr	A pointer to an xattr reader instance.
key	A pointer to the decoded key object.
val_out	Used to return the decoded value. The underlying memory can be released using a single sqfs_free call.

Returns

Zero on success, a negative SQFS_ERROR value on failure.

sqfs_xattr_reader_seek_kv()

SQFS_API int sqfs_xattr_reader_seek_kv	(	sqfs_xattr_reader_t *	xr,
		const sqfs_xattr_id_t *	desc
	)

Resolve an xattr index from an inode to an xattr description.

This function takes an xattr descriptor object and seeks to the meta data block containing the key-value pairs. The individual pairs can then be read using consecutive calls to sqfs_xattr_reader_read_key and sqfs_xattr_reader_read_value.

Parameters

xr	A pointer to an xattr reader instance
desc	The descriptor holding the location of the key-value pairs

Returns

Zero on success, a negative SQFS_ERROR value on failure.

---

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

• include/sqfs/xattr_reader.h