PARAMETERS
nvlp
Address of a pointer to nvlist_t.
nvflag
Specify bit fields defining
nvlist properties:
NV_UNIQUE_NAME
The nvpair names are unique.
NV_UNIQUE_NAME_TYPE
Name-data type combination is unique.
flag
Specify 0. Reserved for future use.
nvl
The nvlist_t to be processed.
dst
The 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.
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. 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(3C).
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.
-
o
-
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_nosleep nv_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:
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 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.
EXAMPLES
/*
* Program to create an nvlist.
*/
#include <stdio.h>
#include <sys/types.h>
#include <string.h>
#include <libnvpair.h>
/* generate a packed nvlist */
static int
create_packed_nvlist(char **buf, uint_t *buflen, int encode)
{
uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
int32_t int32[] = {3, 4, 5};
char *strs[] = {"child0", "child1", "child2"};
int err;
nvlist_t *nvl;
err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0); /* allocate list */
if (err) {
(void) printf("nvlist_alloc() failed\n");
return (err);
}
/* add a value of some types */
if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) ||
(nvlist_add_int32(nvl, "int32", int32[0]) != 0) ||
(nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) ||
(nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) {
nvlist_free(nvl);
return (-1);
}
err = nvlist_size(nvl, buflen, encode);
if (err) {
(void) printf("nvlist_size: %s\n", strerror(err));
nvlist_free(nvl);
return (err);
}
/* pack into contig. memory */
err = nvlist_pack(nvl, buf, buflen, encode, 0);
if (err)
(void) printf("nvlist_pack: %s\n", strerror(err));
/* free the original list */
nvlist_free(nvl);
return (err);
}
/* selectively print nvpairs */
static void
nvlist_lookup_and_print(nvlist_t *nvl)
{
char **str_val;
int i, int_val;
uint_t nval;
if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0)
(void) printf("int32 = %d\n", int_val);
if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval)
== 0) {
(void) printf("string_array =");
for (i = 0; i < nval; i++)
(void) printf(" %s", str_val[i]);
(void) printf("\n");
}
}
/*ARGSUSED*/
int
main(int argc, char *argv[])
{
int err;
char *buf = NULL;
size_t buflen;
nvlist_t *nvl = NULL;
if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
(void) printf("cannot create packed nvlist buffer\n");
return(-1);
}
/* unpack into an nvlist_t */
err = nvlist_unpack(buf, buflen, &nvl, 0);
if (err) {
(void) printf("nvlist_unpack(): %s\n", strerror(err));
return(-1);
}
/* selectively print out attributes */
nvlist_lookup_and_print(nvl);
return(0);
}