ZAP - ZFS Attribute Processor. More...

#include <sys/dmu.h>

Include dependency graph for zap.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	zap_cursor
struct	zap_attribute_t
struct	zap_stats
Defines
#define	ZAP_HISTOGRAM_SIZE 10
Typedefs
typedef enum matchtype	matchtype_t
	Specifies matching criteria for ZAP lookups.
typedef enum zap_flags	zap_flags_t
typedef struct zap_cursor	zap_cursor_t
typedef struct zap_stats	zap_stats_t
Enumerations
enum	matchtype { MT_EXACT, MT_BEST, MT_FIRST }
	Specifies matching criteria for ZAP lookups. More...
enum	zap_flags { ZAP_FLAG_HASH64 = 1 << 0, ZAP_FLAG_UINT64_KEY = 1 << 1, ZAP_FLAG_PRE_HASHED_KEY = 1 << 2 }
Functions
uint64_t	zap_create (objset_t ds, dmu_object_type_t ot, dmu_object_type_t bonustype, int bonuslen, dmu_tx_t tx)
	Create a new zapobj with no attributes and return its object number.
uint64_t	zap_create_norm (objset_t ds, int normflags, dmu_object_type_t ot, dmu_object_type_t bonustype, int bonuslen, dmu_tx_t tx)
uint64_t	zap_create_flags (objset_t os, int normflags, zap_flags_t flags, dmu_object_type_t ot, int leaf_blockshift, int indirect_blockshift, dmu_object_type_t bonustype, int bonuslen, dmu_tx_t tx)
uint64_t	zap_create_link (objset_t os, dmu_object_type_t ot, uint64_t parent_obj, const char name, dmu_tx_t *tx)
int	zap_create_claim (objset_t ds, uint64_t obj, dmu_object_type_t ot, dmu_object_type_t bonustype, int bonuslen, dmu_tx_t tx)
	Create a new zapobj with no attributes from the given (unallocated) object number.
int	zap_create_claim_norm (objset_t ds, uint64_t obj, int normflags, dmu_object_type_t ot, dmu_object_type_t bonustype, int bonuslen, dmu_tx_t tx)
int	zap_destroy (objset_t ds, uint64_t zapobj, dmu_tx_t tx)
	Destroy this zapobj and all its attributes.
int	zap_lookup (objset_t ds, uint64_t zapobj, const char name, uint64_t integer_size, uint64_t num_integers, void *buf)
	Retrieve the contents of the attribute with the given name.
int	zap_lookup_norm (objset_t ds, uint64_t zapobj, const char name, uint64_t integer_size, uint64_t num_integers, void buf, matchtype_t mt, char realname, int rn_len, boolean_t *ncp)
int	zap_lookup_uint64 (objset_t os, uint64_t zapobj, const uint64_t key, int key_numints, uint64_t integer_size, uint64_t num_integers, void *buf)
int	zap_contains (objset_t ds, uint64_t zapobj, const char name)
int	zap_prefetch_uint64 (objset_t os, uint64_t zapobj, const uint64_t key, int key_numints)
int	zap_count_write (objset_t os, uint64_t zapobj, const char name, int add, uint64_t towrite, uint64_t tooverwrite)
int	zap_add (objset_t ds, uint64_t zapobj, const char key, int integer_size, uint64_t num_integers, const void val, dmu_tx_t tx)
	Create an attribute with the given name and value.
int	zap_add_uint64 (objset_t ds, uint64_t zapobj, const uint64_t key, int key_numints, int integer_size, uint64_t num_integers, const void val, dmu_tx_t tx)
int	zap_update (objset_t ds, uint64_t zapobj, const char name, int integer_size, uint64_t num_integers, const void val, dmu_tx_t tx)
	Set the attribute with the given name to the given value.
int	zap_update_uint64 (objset_t os, uint64_t zapobj, const uint64_t key, int key_numints, int integer_size, uint64_t num_integers, const void val, dmu_tx_t tx)
int	zap_length (objset_t ds, uint64_t zapobj, const char name, uint64_t integer_size, uint64_t num_integers)
	Get the length (in integers) and the integer size of the specified attribute.
int	zap_length_uint64 (objset_t os, uint64_t zapobj, const uint64_t key, int key_numints, uint64_t integer_size, uint64_t num_integers)
int	zap_remove (objset_t ds, uint64_t zapobj, const char name, dmu_tx_t *tx)
	Remove the specified attribute.
int	zap_remove_norm (objset_t ds, uint64_t zapobj, const char name, matchtype_t mt, dmu_tx_t *tx)
int	zap_remove_uint64 (objset_t os, uint64_t zapobj, const uint64_t key, int key_numints, dmu_tx_t *tx)
int	zap_count (objset_t ds, uint64_t zapobj, uint64_t count)
	Get the number of attributes in the specified zap object.
int	zap_value_search (objset_t os, uint64_t zapobj, uint64_t value, uint64_t mask, char name)
	Search for an entry by za_first_integer.
int	zap_join (objset_t os, uint64_t fromobj, uint64_t intoobj, dmu_tx_t tx)
	Transfer all the entries from fromobj into intoobj.
int	zap_join_key (objset_t os, uint64_t fromobj, uint64_t intoobj, uint64_t value, dmu_tx_t tx)
	Same as zap_join, but add together any duplicated entries.
int	zap_join_increment (objset_t os, uint64_t fromobj, uint64_t intoobj, dmu_tx_t tx)
	Same as zap_join, but set the values to 'value'.
int	zap_add_int (objset_t os, uint64_t obj, uint64_t value, dmu_tx_t tx)
	Manipulate entries where the name + value are the "same" (the name is a stringified version of the value).
int	zap_remove_int (objset_t os, uint64_t obj, uint64_t value, dmu_tx_t tx)
int	zap_lookup_int (objset_t *os, uint64_t obj, uint64_t value)
int	zap_increment_int (objset_t os, uint64_t obj, uint64_t key, int64_t delta, dmu_tx_t tx)
int	zap_add_int_key (objset_t os, uint64_t obj, uint64_t key, uint64_t value, dmu_tx_t tx)
	Here the key is an int and the value is a different int.
int	zap_update_int_key (objset_t os, uint64_t obj, uint64_t key, uint64_t value, dmu_tx_t tx)
int	zap_lookup_int_key (objset_t os, uint64_t obj, uint64_t key, uint64_t valuep)
int	zap_increment (objset_t os, uint64_t obj, const char name, int64_t delta, dmu_tx_t *tx)
void	zap_cursor_init (zap_cursor_t zc, objset_t ds, uint64_t zapobj)
	Initialize a zap cursor, pointing to the "first" attribute of the zapobj.
void	zap_cursor_fini (zap_cursor_t *zc)
int	zap_cursor_retrieve (zap_cursor_t zc, zap_attribute_t za)
	Get the attribute currently pointed to by the cursor.
void	zap_cursor_advance (zap_cursor_t *zc)
	Advance the cursor to the next attribute.
uint64_t	zap_cursor_serialize (zap_cursor_t *zc)
	Get a persistent cookie pointing to the current position of the zap cursor.
int	zap_cursor_move_to_key (zap_cursor_t zc, const char name, matchtype_t mt)
void	zap_cursor_init_serialized (zap_cursor_t zc, objset_t ds, uint64_t zapobj, uint64_t serialized)
int	zap_get_stats (objset_t ds, uint64_t zapobj, zap_stats_t zs)
	Get statistics about a ZAP object.

Detailed Description

ZAP - ZFS Attribute Processor.

The ZAP is a module which sits on top of the DMU (Data Management Unit) and implements a higher-level storage primitive using DMU objects. Its primary consumer is the ZPL (ZFS Posix Layer).

A "zapobj" is a DMU object which the ZAP uses to stores attributes. Users should use only zap routines to access a zapobj - they should not access the DMU object directly using DMU routines.

The attributes stored in a zapobj are name-value pairs. The name is a zero-terminated string of up to ZAP_MAXNAMELEN bytes (including terminating NULL). The value is an array of integers, which may be 1, 2, 4, or 8 bytes long. The total space used by the array (number of integers * integer length) can be up to ZAP_MAXVALUELEN bytes. Note that an 8-byte integer value can be used to store the location (object number) of another dmu object (which may be itself a zapobj). Note that you can use a zero-length attribute to store a single bit of information - the attribute is present or not.

The ZAP routines are thread-safe. However, you must observe the DMU's restriction that a transaction may not be operated on concurrently.

Any of the routines that return an int may return an I/O error (EIO or ECHECKSUM).

Implementation / Performance Notes

The ZAP is intended to operate most efficiently on attributes with short (49 bytes or less) names and single 8-byte values, for which the microzap will be used. The ZAP should be efficient enough so that the user does not need to cache these attributes.

The ZAP's locking scheme makes its routines thread-safe. Operations on different zapobjs will be processed concurrently. Operations on the same zapobj which only read data will be processed concurrently. Operations on the same zapobj which modify data will be processed concurrently when there are many attributes in the zapobj (because the ZAP uses per-block locking - more than 128 * (number of cpus) small attributes will suffice).

Definition in file zap.h.

Define Documentation

#define ZAP_HISTOGRAM_SIZE 10

Definition at line 401 of file zap.h.

Typedef Documentation

typedef enum matchtype matchtype_t

Specifies matching criteria for ZAP lookups.

typedef struct zap_cursor zap_cursor_t

typedef enum zap_flags zap_flags_t

typedef struct zap_stats zap_stats_t

Enumeration Type Documentation

enum matchtype

Specifies matching criteria for ZAP lookups.

Enumerator:

MT_EXACT	Only find an exact match (non-normalized)
MT_BEST	If there is an exact match, find that, otherwise find the first normalized match.
MT_FIRST	Find the "first" normalized (case and Unicode form) match; the designated "first" match will not change as long as the set of entries with this normalization doesn't change.

Definition at line 92 of file zap.h.

enum zap_flags

Enumerator:

ZAP_FLAG_HASH64	Use 64-bit hash value (serialized cursors will always use 64-bits)
ZAP_FLAG_UINT64_KEY	Key is binary, not string (zap_add_uint64() can be used)
ZAP_FLAG_PRE_HASHED_KEY	First word of key (which must be an array of uint64) is already randomly distributed.

Definition at line 109 of file zap.h.

Function Documentation

int zap_add	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	key,
		int	integer_size,
		uint64_t	num_integers,
		const void *	val,
		dmu_tx_t *	tx
	)

Create an attribute with the given name and value.

Return values:

EEXIST An attribute with the given name already exists

Definition at line 985 of file zap_micro.c.

int zap_add_int	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	value,
		dmu_tx_t *	tx
	)

Manipulate entries where the name + value are the "same" (the name is a stringified version of the value).

Definition at line 1062 of file zap.c.

int zap_add_int_key	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	key,
		uint64_t	value,
		dmu_tx_t *	tx
	)

Here the key is an int and the value is a different int.

Definition at line 1089 of file zap.c.

int zap_add_uint64	(	objset_t *	ds,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints,
		int	integer_size,
		uint64_t	num_integers,
		const void *	val,
		dmu_tx_t *	tx
	)

Definition at line 1028 of file zap_micro.c.

int zap_contains	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name
	)

Definition at line 874 of file zap_micro.c.

int zap_count	(	objset_t *	ds,
		uint64_t	zapobj,
		uint64_t *	count
	)

Get the number of attributes in the specified zap object.

Parameters:

[out] count The number of attributes

Definition at line 707 of file zap_micro.c.

int zap_count_write	(	objset_t *	os,
		uint64_t	zapobj,
		const char *	name,
		int	add,
		uint64_t *	towrite,
		uint64_t *	tooverwrite
	)

Definition at line 1394 of file zap_micro.c.

uint64_t zap_create	(	objset_t *	ds,
		dmu_object_type_t	ot,
		dmu_object_type_t	bonustype,
		int	bonuslen,
		dmu_tx_t *	tx
	)

Create a new zapobj with no attributes and return its object number.

MT_EXACT will cause the zap object to only support MT_EXACT lookups, otherwise any matchtype can be used for lookups.

normflags specifies what normalization will be done. values are: 0: no normalization (legacy on-disk format, supports MT_EXACT matching only) U8_TEXTPREP_TOLOWER: case normalization will be performed. MT_FIRST/MT_BEST matching will find entries that match without regard to case (eg. looking for "foo" can find an entry "Foo"). Eventually, other flags will permit unicode normalization as well.

Definition at line 643 of file zap_micro.c.

int zap_create_claim	(	objset_t *	ds,
		uint64_t	obj,
		dmu_object_type_t	ot,
		dmu_object_type_t	bonustype,
		int	bonuslen,
		dmu_tx_t *	tx
	)

Create a new zapobj with no attributes from the given (unallocated) object number.

Definition at line 621 of file zap_micro.c.

int zap_create_claim_norm	(	objset_t *	ds,
		uint64_t	obj,
		int	normflags,
		dmu_object_type_t	ot,
		dmu_object_type_t	bonustype,
		int	bonuslen,
		dmu_tx_t *	tx
	)

Definition at line 629 of file zap_micro.c.

uint64_t zap_create_flags	(	objset_t *	os,
		int	normflags,
		zap_flags_t	flags,
		dmu_object_type_t	ot,
		int	leaf_blockshift,
		int	indirect_blockshift,
		dmu_object_type_t	bonustype,
		int	bonuslen,
		dmu_tx_t *	tx
	)

Definition at line 660 of file zap_micro.c.

uint64_t zap_create_link	(	objset_t *	os,
		dmu_object_type_t	ot,
		uint64_t	parent_obj,
		const char *	name,
		dmu_tx_t *	tx
	)

Definition at line 953 of file zap.c.

uint64_t zap_create_norm	(	objset_t *	ds,
		int	normflags,
		dmu_object_type_t	ot,
		dmu_object_type_t	bonustype,
		int	bonuslen,
		dmu_tx_t *	tx
	)

Definition at line 650 of file zap_micro.c.

void zap_cursor_advance ( zap_cursor_t * zc )

Advance the cursor to the next attribute.

Definition at line 1323 of file zap_micro.c.

void zap_cursor_fini ( zap_cursor_t * zc )

Definition at line 1220 of file zap_micro.c.

void zap_cursor_init	(	zap_cursor_t *	zc,
		objset_t *	ds,
		uint64_t	zapobj
	)

Initialize a zap cursor, pointing to the "first" attribute of the zapobj.

You must _fini the cursor when you are done with it.

Definition at line 1214 of file zap_micro.c.

void zap_cursor_init_serialized	(	zap_cursor_t *	zc,
		objset_t *	ds,
		uint64_t	zapobj,
		uint64_t	serialized
	)

Definition at line 1201 of file zap_micro.c.

int zap_cursor_move_to_key	(	zap_cursor_t *	zc,
		const char *	name,
		matchtype_t	mt
	)

Definition at line 1331 of file zap_micro.c.

int zap_cursor_retrieve	(	zap_cursor_t *	zc,
		zap_attribute_t *	za
	)

Get the attribute currently pointed to by the cursor.

Return values:

ENOENT At the end of the attributes.

Definition at line 1258 of file zap_micro.c.

uint64_t zap_cursor_serialize ( zap_cursor_t * zc )

Get a persistent cookie pointing to the current position of the zap cursor.

The low 4 bits in the cookie are always zero, and thus can be used as to differentiate a serialized cookie from a different type of value. The cookie will be less than 2^32 as long as there are fewer than 2^22 (4.2 million) entries in the zap object.

Definition at line 1236 of file zap_micro.c.

int zap_destroy	(	objset_t *	ds,
		uint64_t	zapobj,
		dmu_tx_t *	tx
	)

Destroy this zapobj and all its attributes.

Frees the object number using dmu_object_free.

Definition at line 679 of file zap_micro.c.

int zap_get_stats	(	objset_t *	ds,
		uint64_t	zapobj,
		zap_stats_t *	zs
	)

Get statistics about a ZAP object.

Note:: You need to be aware of the internal implementation of the ZAP to correctly interpret some of the statistics. This interface shouldn't be relied on unless you really know what you're doing.

Definition at line 1371 of file zap_micro.c.

int zap_increment	(	objset_t *	os,
		uint64_t	obj,
		const char *	name,
		int64_t	delta,
		dmu_tx_t *	tx
	)

Definition at line 1118 of file zap.c.

int zap_increment_int	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	key,
		int64_t	delta,
		dmu_tx_t *	tx
	)

Definition at line 1139 of file zap.c.

int zap_join	(	objset_t *	os,
		uint64_t	fromobj,
		uint64_t	intoobj,
		dmu_tx_t *	tx
	)

Transfer all the entries from fromobj into intoobj.

Only works on int_size=8 num_integers=1 values. Fails if there are any duplicated entries.

Definition at line 991 of file zap.c.

int zap_join_increment	(	objset_t *	os,
		uint64_t	fromobj,
		uint64_t	intoobj,
		dmu_tx_t *	tx
	)

Same as zap_join, but set the values to 'value'.

Definition at line 1034 of file zap.c.

int zap_join_key	(	objset_t *	os,
		uint64_t	fromobj,
		uint64_t	intoobj,
		uint64_t	value,
		dmu_tx_t *	tx
	)

Same as zap_join, but add together any duplicated entries.

Definition at line 1012 of file zap.c.

int zap_length	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name,
		uint64_t *	integer_size,
		uint64_t *	num_integers
	)

Get the length (in integers) and the integer size of the specified attribute.

Return values:

ENOENT The requested attribute does not exist

Definition at line 884 of file zap_micro.c.

int zap_length_uint64	(	objset_t *	os,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints,
		uint64_t *	integer_size,
		uint64_t *	num_integers
	)

Definition at line 919 of file zap_micro.c.

int zap_lookup	(	objset_t *	os,
		uint64_t	zapobj,
		const char *	name,
		uint64_t	integer_size,
		uint64_t	num_integers,
		void *	buf
	)

Retrieve the contents of the attribute with the given name.

When converting to a larger integer size, the integers will be treated as unsigned (ie. no sign-extension will be performed).

If the attribute is longer than the buffer, as many integers as will fit will be transferred to 'buf'.

Parameters:

[in] num_integers The length (in integers) of 'buf'

Return values:

0	Success
ENOENT	The requested attribute does not exist
EINVAL	integer_size is smaller than the attribute's integer size
EOVERFLOW	The entire attribute was not transferred

Definition at line 770 of file zap_micro.c.

int zap_lookup_int	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	value
	)

Definition at line 1080 of file zap.c.

int zap_lookup_int_key	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	key,
		uint64_t *	valuep
	)

Definition at line 1109 of file zap.c.

int zap_lookup_norm	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name,
		uint64_t	integer_size,
		uint64_t	num_integers,
		void *	buf,
		matchtype_t	mt,
		char *	realname,
		int	rn_len,
		boolean_t *	ncp
	)

Parameters:

[in]	rn_len	If nonzero, realname will be set to the name of the found entry (which may be different from the requested name if matchtype is not MT_EXACT).
[in,out]	ncp	If not NULL, it will be set if there is another name with the same case/unicode normalized form.

Definition at line 778 of file zap_micro.c.

int zap_lookup_uint64	(	objset_t *	os,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints,
		uint64_t	integer_size,
		uint64_t	num_integers,
		void *	buf
	)

Definition at line 850 of file zap_micro.c.

int zap_prefetch_uint64	(	objset_t *	os,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints
	)

Definition at line 827 of file zap_micro.c.

int zap_remove	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name,
		dmu_tx_t *	tx
	)

Remove the specified attribute.

Return values:

ENOENT The specified attribute does not exist

Definition at line 1134 of file zap_micro.c.

int zap_remove_int	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	value,
		dmu_tx_t *	tx
	)

Definition at line 1071 of file zap.c.

int zap_remove_norm	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name,
		matchtype_t	mt,
		dmu_tx_t *	tx
	)

Definition at line 1140 of file zap_micro.c.

int zap_remove_uint64	(	objset_t *	os,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints,
		dmu_tx_t *	tx
	)

Definition at line 1175 of file zap_micro.c.

int zap_update	(	objset_t *	ds,
		uint64_t	zapobj,
		const char *	name,
		int	integer_size,
		uint64_t	num_integers,
		const void *	val,
		dmu_tx_t *	tx
	)

Set the attribute with the given name to the given value.

If an attribute with the given name does not exist, it will be created. If an attribute with the given name already exists, the previous value will be overwritten. The integer_size may be different from the existing attribute's integer size, in which case the attribute's integer size will be updated to the new value.

Definition at line 1053 of file zap_micro.c.

int zap_update_int_key	(	objset_t *	os,
		uint64_t	obj,
		uint64_t	key,
		uint64_t	value,
		dmu_tx_t *	tx
	)

Definition at line 1099 of file zap.c.

int zap_update_uint64	(	objset_t *	os,
		uint64_t	zapobj,
		const uint64_t *	key,
		int	key_numints,
		int	integer_size,
		uint64_t	num_integers,
		const void *	val,
		dmu_tx_t *	tx
	)

Definition at line 1109 of file zap_micro.c.

int zap_value_search	(	objset_t *	os,
		uint64_t	zapobj,
		uint64_t	value,
		uint64_t	mask,
		char *	name
	)

Search for an entry by za_first_integer.

Parameters:

[in]	mask	If mask==0, the match must be exact (ie, same as mask=-1ULL)
[out]	name	The name of the entry whose (za_first_integer & mask) == (value & mask). The string pointed to by name must be at least 256 bytes long.

Return values:

ENOENT No entry was found for the given value and mask

Definition at line 966 of file zap.c.

sys/zap.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Implementation / Performance Notes

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation