Address of buffer to pack nvlist into. Must be 8-byte aligned. If NULL, library will allocate memory.

buf

Buffer containing packed nvlist.

buflen

Size of buffer bufp or buf points to.

encoding

Encoding method for packing.

nvo

Pluggable allocator operations pointer (nv_alloc_ops_t).

nva

A pointer to an nv_alloc_t structure to be used for the specified nvlist_t.

Description

List Manipulation

The nvlist_alloc() function allocates a new name-value pair list and updates nvlp
to point to the handle. The nvflag argument specifies nvlist properties to
remain persistent across packing, unpacking, and duplication. If NV_UNIQUE_NAME was specified for nvflag,
existing nvpairs with matching names are removed before the new nvpair is
added. If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing nvpairs with matching names and
data types are removed before the new nvpair is added. See nvlist_add_byte(3NVPAIR)
for more information.

The nvlist_xalloc() function is identical to nvlist_alloc() except that nvlist_xalloc() can use
a different allocator, as described in the Pluggable Allocators section.

The nvlist_free() function frees a name-value pair list.

The nvlist_size() function returns the minimum size of a contiguous buffer large
enough to pack nvl. The encoding parameter specifies the method of encoding
when packing nvl. Supported encoding methods are:

If *bufp is not NULL, *bufp is expected to be a caller-allocated buffer of size *buflen.

If *bufp is NULL, the library will allocate memory and update *bufp to point to the memory and update *buflen to contain the size of the allocated memory.

The nvlist_xpack() function is identical to nvlist_pack() except that nvlist_xpack() can use
a different allocator.

The nvlist_unpack() function takes a buffer with a packed nvlist_t and unpacks
it into a searchable nvlist_t. The library allocates memory for nvlist_t. The
caller is responsible for freeing the memory by calling nvlist_free().

The nvlist_xunpack() function is identical to nvlist_unpack() except that nvlist_xunpack() can use
a different allocator.

The nvlist_dup() function makes a copy of nvl and updates nvlp to
point to the copy.

The nvlist_xdup() function is identical to nvlist_dup() except that nvlist_xdup() can use
a different allocator.

The nvlist_merge() function adds copies of all name-value pairs from nvl to
dst. Name-value pairs in dst are replaced with name-value pairs from
nvl that have identical names (if dst has the type NV_UNIQUE_NAME) or
identical names and types (if dst has the type NV_UNIQUE_NAME_TYPE).

The nvlist_lookup_nv_alloc() function retrieves the pointer to the allocator that was used
when manipulating a name-value pair list.

Pluggable Allocators

Using Pluggable Allocators

The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions provide an interface to specify the
allocator to be used when manipulating a name-value pair list.

The nv_alloc_init() function determines the allocator properties and puts them into the
nva argument. The application must specify the nv_arg and nvo arguments and
an optional variable argument list. The optional arguments are passed to the (*nv_ao_init())
function.

The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack() and nvlist_xdup().

The nv_alloc_reset() function is responsible for resetting the allocator properties to the
data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is specified, nv_alloc_reset() has
no effect.

The nv_alloc_fini() function destroys the allocator properties determined by nv_alloc_init(). When a
(*nv_ao_fini()) function is specified, it is called from nv_alloc_fini().

The disposition of the allocated objects and the memory used to store
them is left to the allocator implementation.

The nv_alloc_nosleepnv_alloc_t can be used with nvlist_xalloc() to mimic the behavior
of nvlist_alloc().

The nvpair allocator framework provides a pointer to the operation structure of
a fixed buffer allocator. This allocator, nv_fixed_ops, uses a pre-allocated buffer for
memory allocations. It is intended primarily for kernel use and is described
on nvlist_alloc(9F).

An example program that uses the pluggable allocator functionality is provided on
nvlist_alloc(9F).

Creating Pluggable Allocators

Any producer of name-value pairs can specify its own allocator functions. The
application must provide the following pluggable allocator operations:

The nva argument of the allocator implementation is always the first argument.

The optional (*nv_ao_init()) function is responsible for filling the data specified by
nv_alloc_init() into the nva_arg argument. The (*nv_ao_init()) function is only called
when nv_alloc_init() is executed.

The optional (*nv_ao_fini()) function is responsible for the cleanup of the allocator
implementation. It is called by nv_alloc_fini().

The required (*nv_ao_alloc()) function is used in the nvpair allocation framework for
memory allocation. The sz argument specifies the size of the requested buffer.

The optional (*nv_ao_reset()) function is responsible for resetting the nva_arg argument to
the data specified by nv_alloc_init().

The required (*nv_ao_free()) function is used in the nvpair allocator framework for
memory deallocation. The buf argument is a pointer to a block previously
allocated by the (*nv_ao_alloc()) function. The size argument sz must exactly match the
original allocation.

The disposition of the allocated objects and the memory used to store
them is left to the allocator implementation.

Return Values

These functions return 0 on success and an error value on failure.

The nvlist_lookup_nv_alloc() function returns a pointer to an allocator.