PARAMETERS
nvlp
Address of a pointer to list of name-value pairs (nvlist_t).
nvflag
Specify bit fields defining
nvlist_t properties:
NV_UNIQUE_NAME
nvpair names are unique.
NV_UNIQUE_NAME_TYPE
Name-data type combination is unique
kmflag
Kernel memory allocation policy, either KM_SLEEP or KM_NOSLEEP.
nvl
nvlist_t to be processed.
dst
Destination nvlist_t.
size
Pointer to buffer to contain the encoded size.
bufp
Address of buffer to pack nvlist into. Must be 8-byte aligned. If NULL, library will allocate memory.
buf
Buffer containing packed nvlist_t.
buflen
Size of buffer bufp or buf points to.
encoding
Encoding method for packing.
nvo
Pluggable allocator operations pointer (nv_alloc_ops_t).
nva
Points to a 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 argument
nvflag specifies
nvlist_t properties to remain persistent across packing, unpacking, and duplication.
If
NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with matching names are removed before the new nvpair is added. If
NV_UNIQUE_NAME_TYPE is specified for nvflag, existing nvpairs with matching names and data types are removed before the new nvpair is added. See
nvlist_add_byte(9F) for more details.
The
nvlist_xalloc() function differs from
nvlist_alloc() in 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. If
nvl is a null pointer, no action occurs.
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:
NV_ENCODE_NATIVE
Straight bcopy() as described in bcopy(9F).
NV_ENCODE_XDR
Use XDR encoding, suitable for sending to another host.
The
nvlist_pack() function packs
nvl into contiguous memory starting at *
bufp. The
encoding parameter specifies the method of encoding (see above).
-
o
-
If *bufp is not NULL, *bufp is expected to be a caller-allocated buffer of size * buflen. The kmflag argument is ignored.
-
o
-
If *bufp is NULL, the library allocates memory and updates *bufp to point to the memory and updates * buflen to contain the size of the allocated memory. The value of kmflag indicates the memory allocation policy
The
nvlist_xpack() function differs from
nvlist_pack() in 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 differs from
nvlist_unpack() in 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 differs from
nvlist_dup() in that
nvlist_xdup() can use a different allocator.
The
nvlist_merge() function adds copies of all name-value pairs from
nvlist_t nvl to
nvlist_t dst. Name-value pairs in dst are replaced with name-value pairs from
nvl which 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 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 that specifies the allocator to be used when manipulating a name-value pair list.
The
nv_alloc_init() determines allocator properties and puts them into the
nva argument. You need to specify the
nv_arg argument, the
nvo argument 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 resets the allocator properties to the data specified by
nv_alloc_init(). When no (*
nv_ao_reset()) function is specified,
nv_alloc_reset() is without effect.
The
nv_alloc_fini() destroys the allocator properties determined by
nv_alloc_init(). When a (*
nv_ao_fini()) routine 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_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and KM_NOSLEEP, respectively.
o nv_alloc_nosleep
o nv_alloc_sleep
The nvpair framework provides a fixed-buffer allocator, accessible via nv_fixed_ops.
o nv_fixed_ops
Given a buffer size and address, the fixed-buffer allocator allows for the creation of nvlists in contexts where malloc or kmem_alloc services may not be available. The fixed-buffer allocator is designed primarily to support the creation of nvlists.
Memory freed using
nvlist_free(), pair-removal, or similar routines is not reclaimed.
When used to initialize the fixed-buffer allocator, nv_alloc_init should be called as follows:
int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
void *bufptr, size_t sz);
When invoked on a fixed-buffer, the
nv_alloc_reset() function resets the fixed buffer and prepares it for re-use. The framework consumer is responsible for freeing the buffer passed to
nv_alloc_init().
CREATING PLUGGABLE ALLOCATORS
Any producer of name-value pairs may possibily specify his own allocator routines. You must provide the following pluggable allocator operations in the allocator implementation.
int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
void (*nv_ao_fini)(nv_alloc_t *nva);
void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
void (*nv_ao_reset)(nv_alloc_t *nva);
void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
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 called only 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 de-allocation. The argument buf is a pointer to a block previously allocated by (*
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.
EXAMPLES
/*
* using the fixed-buffer allocator.
*/
#include <sys/nvpair.h>
/* initialize the nvpair allocator framework */
static nv_alloc_t *
init(char *buf, size_t size)
{
nv_alloc_t *nvap;
if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
return (NULL);
if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
return (nvap);
return (NULL);
}
static void
fini(nv_alloc_t *nvap)
{
nv_alloc_fini(nvap);
kmem_free(nvap, sizeof(nv_alloc_t));
}
static int
interrupt_context(nv_alloc_t *nva)
{
nvlist_t *nvl;
int error;
if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
return (-1);
if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
error = send_nvl(nvl);
nvlist_free(nvl);
return (error);
}