Tribblix: manual page: nvlist

NVLIST_ALLOC(3NVPAIR) Name-value Pair Library Functions

NAME

nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack,
nvlist_dup, nvlist_merge, nvlist_xalloc, nvlist_xpack,
nvlist_xunpack, nvlist_xdup, nvlist_lookup_nv_alloc, nv_alloc_init,
nv_alloc_reset, nv_alloc_fini - manage a name-value pair list

SYNOPSIS

cc [ flag... ] file... -lnvpair [ library... ]
#include <libnvpair.h>

int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag);

int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag,
nv_alloc_t * nva);

void nvlist_free(nvlist_t *nvl);

int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);

int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen,
int encoding, int flag);

int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen,
int encoding, nv_alloc_t * nva);

int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp,
int flag);

int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
nv_alloc_t * nva);

int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);

int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp,
nv_alloc_t * nva);

int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);

nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl);

int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
/* args */ ...);

void nv_alloc_reset(nv_alloc_t *nva);

void nv_alloc_fini(nv_alloc_t *nva);

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.

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.

ERRORS

These functions will fail if:

EINVAL
There is an invalid argument.

The nvlist_alloc(), nvlist_dup(), nvlist_pack(), nvlist_unpack(),
nvlist_merge(), nvlist_xalloc(), nvlist_xdup(), nvlist_xpack(), and
nvlist_xunpack() functions will fail if:

ENOMEM
There is insufficient memory.

The nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and
nvlist_xunpack() functions will fail if:

EFAULT
An encode/decode error occurs.

ENOTSUP
An encode/decode method is not supported.

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);
}

ATTRIBUTES