NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO
cc [ flag... ] file... -lnvpair [ library... ] #include <libnvpair.h>int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag);
Address of a pointer to nvlist_t.
Specify bit fields defining nvlist properties:
The nvpair names are unique.
Name-data type combination is unique
Specify 0. Reserved for future use.
The nvlist_t to be processed.
Pointer to buffer to contain the encoded size.
Address of buffer to pack nvlist into. Must be 8-byte aligned. If NULL, library will allocate memory.
Buffer containing packed nvlist.
Size of buffer bufp or buf points to.
Encoding method for packing.
The nvlist_alloc() function allocates a new name-value pair list and updates nvlp to point to the handle. The argument nvflag specifies nvlist properties to remain persistent across packing, unpacking, and duplication.
The nvlist_free() function frees a name-value pair list.
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:
Straight bcopy() as described in bcopy(3C).
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).
If *bufp is not NULL, *bufp is expected to be a caller-allocated buffer of size *buflen.
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_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_dup() function makes a copy of nvl and updates nvlp to point to the copy.
These functions return 0 on success and an error value on failure.
These functions will fail if:
There is an invalid argument.
The nvlist_alloc(), nvlist_dup(), nvlist_pack(), and nvlist_unpack() functions will fail if:
There is insufficient memory.
The nvlist_pack() and nvlist_unpack() functions will fail if:
An encode/decode error occurs.
An encode/decode method is not supported.
/* * Program to read or create an nvlist. */ #include <stdio.h> #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> #include <string.h> #include <unistd.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}; int16_t int16[] = {0, 1, 2}; int32_t int32[] = {3, 4, 5}; uint64_t uint64[] = {0x100000007, 0x100000008, 0x100000009}; 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 each type */ if ((nvlist_add_boolean(nvl, "bool") != 0) || (nvlist_add_byte(nvl, "byte", bytes[0]) != 0) || (nvlist_add_int16(nvl, "int16", int16[0]) != 0) || (nvlist_add_int32(nvl, "int32", int32[0]) != 0) || (nvlist_add_uint64(nvl, "uint64", uint64[0]) != 0) || (nvlist_add_string(nvl, "string", strs[0]) != 0) || (nvlist_add_byte_array(nvl, "byte_array", bytes, 4) != 0) || (nvlist_add_int16_array(nvl, "int16_array", int16, 3) != 0) || (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) || (nvlist_add_uint64_array(nvl, "uint64_array", uint64, 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)); 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); } /* read a packed nvlist from file or create a packed nvlist */ static int get_nvlist_buf(char *file, char **buf, size_t *buflen) { int fd, rv; struct stat sbuf; if (file == NULL) return (create_packed_nvlist(buf, buflen, NV_ENCODE_NATIVE)); /* read from file */ fd = open(file, O_RDONLY); if (fd == -1) { (void) printf("cannot open file %s\n", file); return (-1); } (void) fstat(fd, &sbuf); *buflen = sbuf.st_size; *buf = malloc(*buflen); if (*buf == NULL) { (void) printf("out of memory\n"); return (-1); } rv = read(fd, *buf, *buflen); (void) close(fd); return (rv); } /* 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"); } } void main(int argc, char *argv[]) { int c, err; char *file = NULL, *buf = NULL; size_t buflen; nvlist_t *nvl = NULL; while ((c = getopt(argc, argv, "r:")) != EOF) switch (c) { case 'r': file = optarg; break; default: (void) printf("Usage: %s [ -r file ]", argv[0]); return; } if (get_nvlist_buf(file, &buf, &buflen) != 0) { (void) printf("cannot get packed nvlist buffer\n"); return; } /* unpack into an nvlist_t */ err = nvlist_unpack(buf, buflen, &nvl, 0); if (err) { (void) printf("nvlist_unpack(): %s\n", strerror(err)); return; } /* selectively print out attributes */ nvlist_lookup_and_print(nvl); return; }
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
MT-Level | MT-Safe |
NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO