Name-value Pair Library Functions nvlistalloc(3NVPAIR)
NAME
nvlistalloc, nvlistfree, nvlistsize, nvlistpack,
nvlistunpack, nvlistdup, nvlistmerge, nvlistxalloc,
nvlistxpack, nvlistxunpack, nvlistxdup,
nvlistlookupnvalloc, nvallocinit, nvallocreset,
nvallocfini - manage a name-value pair list
SYNOPSIS
cc [ flag... ] file... -lnvpair [ library... ]
#include
int nvlistalloc(nvlistt **nvlp, uintt nvflag, int flag);
int nvlistxalloc(nvlistt **nvlp, uintt nvflag,
nvalloct * nva);
void nvlistfree(nvlistt *nvl);
int nvlistsize(nvlistt *nvl, sizet *size, int encoding);
int nvlistpack(nvlistt *nvl, char **bufp, sizet *buflen,
int encoding, int flag);
int nvlistxpack(nvlistt *nvl, char **bufp, sizet *buflen,
int encoding, nvalloct * nva);
int nvlistunpack(char *buf, sizet buflen, nvlistt **nvlp,
int flag);
int nvlistxunpack(char *buf, sizet buflen, nvlistt **nvlp,
nvalloct * nva);
int nvlistdup(nvlistt *nvl, nvlistt **nvlp, int flag);
int nvlistxdup(nvlistt *nvl, nvlistt **nvlp,
nvalloct * nva);
int nvlistmerge(nvlistt *dst, nvlistt *nvl, int flag);
nvalloct * nvlistlookupnvalloc(nvlistt *nvl);
SunOS 5.11 Last change: 2 Feb 2004 1
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
int nvallocinit(nvalloct *nva, const nvallocopst *nvo,
/* args */ ...);
void nvallocreset(nvalloct *nva);
void nvallocfini(nvalloct *nva);
PARAMETERS
nvlp Address of a pointer to nvlistt.
nvflag Specify bit fields defining nvlist properties:
NVUNIQUENAME The nvpair names are
unique.
NVUNIQUENAMETYPE Name-data type combina-
tion is unique.
flag Specify 0. Reserved for future use.
nvl The nvlistt to be processed.
dst The destination nvlistt.
size Pointer to buffer to contain the encoded size.
bufp Address of buffer to pack nvlist into. Must be
8-byte aligned. If NUL, library will allocate
memory.
buf Buffer containing packed nvlist.
buflen Size of buffer bufp or buf points to.
encoding Encoding method for packing.
SunOS 5.11 Last change: 2 Feb 2004 2
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
nvo Pluggable allocator operations pointer
(nvallocopst).
nva A pointer to an nvalloct structure to be used
for the specified nvlistt.
DESCRIPTION
List Manipulation
The nvlistalloc() 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
NVUNIQUENAME was specified for nvflag, existing nvpairs
with matching names are removed before the new nvpair is
added. If NVUNIQUENAMETYPE was specified for nvflag,
existing nvpairs with matching names and data types are
removed before the new nvpair is added. See
nvlistaddbyte(3NVPAIR) for more information.
The nvlistxalloc() function is identical to nvlistalloc()
except that nvlistxalloc() can use a different allocator,
as described in the Pluggable Allocators section.
The nvlistfree() function frees a name-value pair list.
The nvlistsize() 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:
NVENCODENATIVE Straight bcopy() as described in
bcopy(3C).
NVENCODEXDR Use XDR encoding, suitable for sending
to another host.
The nvlistpack() function packs nvl into contiguous memory
starting at *bufp. The encoding parameter specifies the
method of encoding (see above).
o If *bufp is not NUL, *bufp is expected to be a
caller-allocated buffer of size *buflen.
o If *bufp is NUL, the library will allocate memory
SunOS 5.11 Last change: 2 Feb 2004 3
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
and update *bufp to point to the memory and update
*buflen to contain the size of the allocated
memory.
The nvlistxpack() function is identical to nvlistpack()
except that nvlistxpack() can use a different allocator.
The nvlistunpack() function takes a buffer with a packed
nvlistt and unpacks it into a searchable nvlistt. The
library allocates memory for nvlistt. The caller is respon-
sible for freeing the memory by calling nvlistfree().
The nvlistxunpack() function is identical to
nvlistunpack() except that nvlistxunpack() can use a dif-
ferent allocator.
The nvlistdup() function makes a copy of nvl and updates
nvlp to point to the copy.
The nvlistxdup() function is identical to nvlistdup()
except that nvlistxdup() can use a different allocator.
The nvlistmerge() 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 NVUNIQUENAME) or identical names and
types (if dst has the type NVUNIQUENAMETYPE).
The nvlistlookupnvalloc() function retrieves the pointer
to the allocator that was used when manipulating a name-
value pair list.
Pluggable Allocators
Using Pluggable Allocators
The nvallocinit(), nvallocreset() and nvallocfini()
functions provide an interface to specify the allocator to
be used when manipulating a name-value pair list.
The nvallocinit() function determines the allocator pro-
perties and puts them into the nva argument. The application
must specify the nvarg and nvo arguments and an optional
variable argument list. The optional arguments are passed to
the (*nvaoinit()) function.
SunOS 5.11 Last change: 2 Feb 2004 4
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
The nva argument must be passed to nvlistxalloc(),
nvlistxpack(), nvlistxunpack() and nvlistxdup().
The nvallocreset() function is responsible for resetting
the allocator properties to the data specified by
nvallocinit(). When no (*nvaoreset()) function is speci-
fied, nvallocreset() has no effect.
The nvallocfini() function destroys the allocator proper-
ties determined by nvallocinit(). When a (*nvaofini())
function is specified, it is called from nvallocfini().
The disposition of the allocated objects and the memory used
to store them is left to the allocator implementation.
The nvallocnosleep nvalloct can be used with
nvlistxalloc() to mimic the behavior of nvlistalloc().
The nvpair allocator framework provides a pointer to the
operation structure of a fixed buffer allocator. This allo-
cator, nvfixedops, uses a pre-allocated buffer for memory
allocations. It is intended primarily for kernel use and is
described on nvlistalloc(9F).
An example program that uses the pluggable allocator func-
tionality is provided on nvlistalloc(9F).
Creating Pluggable Allocators
Any producer of name-value pairs can specify its own alloca-
tor functions. The application must provide the following
pluggable allocator operations:
int (*nvaoinit)(nvalloct *nva, valist nvvalist);
void (*nvaofini)(nvalloct *nva);
void *(*nvaoalloc)(nvalloct *nva, sizet sz);
void (*nvaoreset)(nvalloct *nva);
void (*nvaofree)(nvalloct *nva, void *buf, sizet sz);
The nva argument of the allocator implementation is always
the first argument.
The optional (*nvaoinit()) function is responsible for
filling the data specified by nvallocinit() into the
SunOS 5.11 Last change: 2 Feb 2004 5
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
nvaarg argument. The (*nvaoinit()) function is only
called when nvallocinit() is executed.
The optional (*nvaofini()) function is responsible for the
cleanup of the allocator implementation. It is called by
nvallocfini().
The required (*nvaoalloc()) function is used in the nvpair
allocation framework for memory allocation. The sz argument
specifies the size of the requested buffer.
The optional (*nvaoreset()) function is responsible for
resetting the nvaarg argument to the data specified by
nvallocinit().
The required (*nvaofree()) 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
(*nvaoalloc()) 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 nvlistlookupnvalloc() function returns a pointer to
an allocator.
ERORS
These functions will fail if:
EINVAL There is an invalid argument.
The nvlistalloc(), nvlistdup(), nvlistpack(),
nvlistunpack(), nvlistmerge(), nvlistxalloc(),
nvlistxdup(), nvlistxpack(), and nvlistxunpack() func-
tions will fail if:
ENOMEM There is insufficient memory.
SunOS 5.11 Last change: 2 Feb 2004 6
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
The nvlistpack(), nvlistunpack(), nvlistxpack(), and
nvlistxunpack() 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 int
createpackednvlist(char **buf, uintt *buflen, int encode)
{
uchart bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
int32t int32[] = {3, 4, 5};
char *strs[] = {"child0", "child1", "child2"};
int err;
nvlistt *nvl;
err = nvlistalloc(&nvl, NVUNIQUENAME, 0); /* allocate list */
if (err) {
(void) printf("nvlistalloc() failed\n");
return (err);
}
/* add a value of some types */
if ((nvlistaddbyte(nvl, "byte", bytes[0]) != 0)
(nvlistaddint32(nvl, "int32", int32[0]) != 0)
(nvlistaddint32array(nvl, "int32array", int32, 3) != 0)
(nvlistaddstringarray(nvl, "stringarray", strs, 3) != 0)) {
nvlistfree(nvl);
return (-1);
}
err = nvlistsize(nvl, buflen, encode);
if (err) {
(void) printf("nvlistsize: %s\n", strerror(err));
nvlistfree(nvl);
return (err);
}
/* pack into contig. memory */
err = nvlistpack(nvl, buf, buflen, encode, 0);
SunOS 5.11 Last change: 2 Feb 2004 7
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
if (err)
(void) printf("nvlistpack: %s\n", strerror(err));
/* free the original list */
nvlistfree(nvl);
return (err);
}
/* selectively print nvpairs */
static void
nvlistlookupandprint(nvlistt *nvl)
{
char **strval;
int i, intval;
uintt nval;
if (nvlistlookupint32(nvl, "int32", &intval) == 0)
(void) printf("int32 = %d\n", intval);
if (nvlistlookupstringarray(nvl, "stringarray", &strval, &nval)
== 0) {
(void) printf("stringarray =");
for (i = 0; i < nval; i])
(void) printf(" %s", strval[i]);
(void) printf("\n");
}
}
/*ARGSUSED*/
int
main(int argc, char *argv[])
{
int err;
char *buf = NUL;
sizet buflen;
nvlistt *nvl = NUL;
if (createpackednvlist(&buf, &buflen, NVENCODEXDR) != 0) {
(void) printf("cannot create packed nvlist buffer\n");
return(-1);
}
/* unpack into an nvlistt */
err = nvlistunpack(buf, buflen, &nvl, 0);
if (err) {
(void) printf("nvlistunpack(): %s\n", strerror(err));
return(-1);
}
/* selectively print out attributes */
nvlistlookupandprint(nvl);
return(0);
}
SunOS 5.11 Last change: 2 Feb 2004 8
Name-value Pair Library Functions nvlistalloc(3NVPAIR)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
libnvpair(3LIB), attributes(5), nvlistalloc(9F)
SunOS 5.11 Last change: 2 Feb 2004 9
|
