nvlist_free(3NVPAIR)

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO

NAME

nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup- 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);
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_unpack(char *buf, size_t buflen, nvlist_t **nvlp, int flag);
int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);

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.

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.

DESCRIPTION

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:

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).

• 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.

RETURN VALUES

These functions return 0 on success and an error value on failure.

ERRORS

All five functions will fail if:

EINVAL

There is an invalid argument.

The nvlist_alloc(), nvlist_dup(), nvlist_pack(), and nvlist_unpack() functions will fail if:

ENOMEM

There is insufficient memory.

The nvlist_pack() and nvlist_unpack() functions will fail if:

EFAULT

An encode/decode error occurs.

ENOTSUP

An encode/decode method is not supported.

EXAMPLES

/*
 * 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\
");
        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\
", strerror(err));
        return (err);
    }

    /* pack into contig. memory */
    err = nvlist_pack(nvl, buf, buflen, encode, 0);
    if (err)
        (void) printf("nvlist_pack: %s\
", 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\
", file);
        return (-1);
    }
    (void) fstat(fd, &sbuf);
    *buflen = sbuf.st_size;
    *buf = malloc(*buflen);
    if (*buf == NULL) {
        (void) printf("out of memory\
");
        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\
", 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("\
");
    }
}

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\
");
        return;
    }

    /* unpack into an nvlist_t */
    err = nvlist_unpack(buf, buflen, &nvl, 0);
    if (err) {
        (void) printf("nvlist_unpack(): %s\
", strerror(err));
        return;
    }

    /* selectively print out attributes */
    nvlist_lookup_and_print(nvl);
    return;
}

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
MT-Level	MT-Safe

SEE ALSO

libnvpair(3NVPAIR), attributes(5)

SunOS 5.9  Last Revised 21 Aug 2001

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO