Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
NAME
nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack,
nvlist_unpack, nvlist_dup, nvlist_merge, nvlist_flag,
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
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);
uint_t nvlist_nvflag(nvlist_t *nvl);
SunOS 5.11 Last change: 14 Jul 2010 1
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
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 combina-
tion is unique.See nvlist_add_boolean_value(3NVPAIR) for a
description of these flags values, and for behavior when neither is specified. 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 be8-byte aligned. If NULL, library will allocate
memory. buf Buffer containing packed nvlist.SunOS 5.11 Last change: 14 Jul 2010 2
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
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 ManipulationThe 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. IfNV_UNIQUE_NAME was specified for nvflag, existing nvpairs
with matching names are removed before the new nvpair isadded. 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. Seenvlist_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_nvflag() function returns the nvflag value for
the nvlist, specified when it was allocated usingnvlist_alloc() or nvlist_xalloc().
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.SunOS 5.11 Last change: 14 Jul 2010 3
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
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 acaller-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 respon-
sible for freeing the memory by calling nvlist_free().
The nvlist_xunpack() function is identical to
nvlist_unpack() except that nvlist_xunpack() can use a dif-
ferent 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 AllocatorsThe nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini()
functions provide an interface to specify the allocator tobe used when manipulating a name-value pair list.
SunOS 5.11 Last change: 14 Jul 2010 4
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
The nv_alloc_init() function determines the allocator pro-
perties and puts them into the nva argument. The applicationmust specify the nv_arg and nvo arguments and an optional
variable argument list. The optional arguments are passed tothe (*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 bynv_alloc_init(). When no (*nv_ao_reset()) function is speci-
fied, nv_alloc_reset() has no effect.
The nv_alloc_fini() function destroys the allocator proper-
ties 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 theoperation structure of a fixed buffer allocator. This allo-
cator, nv_fixed_ops, uses a pre-allocated buffer for memory
allocations. It is intended primarily for kernel use and isdescribed on nvlist_alloc(9F).
An example program that uses the pluggable allocator func-
tionality is provided on nvlist_alloc(9F).
Creating Pluggable AllocatorsAny producer of name-value pairs can specify its own alloca-
tor 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);
SunOS 5.11 Last change: 14 Jul 2010 5
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
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 bynv_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 argu-
ment 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(),
SunOS 5.11 Last change: 14 Jul 2010 6
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
nvlist_xdup(), nvlist_xpack(), and nvlist_xunpack() func-
tions 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
#include
#include
#include
/* generate a packed nvlist */ static intcreate_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) {SunOS 5.11 Last change: 14 Jul 2010 7
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
(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 voidnvlist_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));
SunOS 5.11 Last change: 14 Jul 2010 8
Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
return(-1);
} /* selectively print out attributes */nvlist_lookup_and_print(nvl);
return(0); }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________________|______________________________|
| Interface Stability | Committed ||____________________________|______________________________|
| MT-Level | MT-Safe |
|____________________________|______________________________|
SEE ALSO
libnvpair(3LIB), attributes(5),nvlist_add_boolean_value(3NVPAIR), nvlist_alloc(9F)
SunOS 5.11 Last change: 14 Jul 2010 9