nvlist_alloc(9F)

NAME

     nvlist_alloc,   nvlist_free,    nvlist_size,    nvlist_pack,
     nvlist_unpack, nvlist_dup - manage a name-value pair list

SYNOPSIS

     #include <sys/nvpair.h>

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

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

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

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

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

     nvlp  Address of a  pointer  to  list  of  name-value  pairs
           (nvlist_t).

     nvflag
           Specify bit fields defining nvlist_t properties:

           NV_UNIQUE_NAME
                 The nvpair names are unique.

           NV_UNIQUE_NAME_TYPE
                 Name-data type combination is unique

     kmflag
           Kernel memory allocation policy,  either  KM_SLEEP  or
           KM_NOSLEEP.

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

     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_t 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(9F).

     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. The kmflag
           argument is ignored.

        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 value
           of kmflag indicates the memory allocation policy

     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_dup() function makes a copy of  nvl  and  updates
     nvlp to point to the copy.

RETURN VALUES

     For nvlist_alloc(), nvlist_dup():

     0     success

     EINVAL
           invalid argument

     ENOMEM
           insufficient memory

     For nvlist_pack(), nvlist_unpack():

     0     success

     EINVAL
           invalid argument

     ENOMEM
           insufficient memory

     EFAULT
           encode/decode error

     ENOTSUP
           encode/decode method not supported

     For nvlist_size():

     0     success

     EINVAL
           invalid argument

CONTEXT

     The  nvlist_alloc(),  nvlist_pack(),  nvlist_unpack(),   and
     nvlist_dup()  functions can be called from interrupt context
     only if the KM_NOSLEEP flag is set. They can be called  from
     user context with any valid flag.