1 NVLIST_ALLOC(3NVPAIR)  Name-value Pair Library Functions NVLIST_ALLOC(3NVPAIR)
   2 
   3 
   4 
   5 NAME
   6        nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack,
   7        nvlist_dup, nvlist_merge, nvlist_xalloc, nvlist_xpack, nvlist_xunpack,
   8        nvlist_xdup, nvlist_lookup_nv_alloc, nv_alloc_init, nv_alloc_reset,
   9        nv_alloc_fini - manage a name-value pair list
  10 
  11 SYNOPSIS
  12        cc [ flag... ] file... -lnvpair [ library... ]
  13        #include <libnvpair.h>
  14 
  15        int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag);
  16 
  17 
  18        int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag,
  19             nv_alloc_t * nva);
  20 
  21 
  22        void nvlist_free(nvlist_t *nvl);
  23 
  24 
  25        int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
  26 
  27 
  28        int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen,
  29             int encoding, int flag);
  30 
  31 
  32        int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen,
  33             int encoding, nv_alloc_t * nva);
  34 
  35 
  36        int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp,
  37             int flag);
  38 
  39 
  40        int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
  41             nv_alloc_t * nva);
  42 
  43 
  44        int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);
  45 
  46 
  47        int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp,
  48             nv_alloc_t * nva);
  49 
  50 
  51        int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
  52 
  53 
  54        nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl);
  55 
  56 
  57        int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
  58             /* args */ ...);
  59 
  60 
  61        void nv_alloc_reset(nv_alloc_t *nva);
  62 
  63 
  64        void nv_alloc_fini(nv_alloc_t *nva);
  65 
  66 
  67 PARAMETERS
  68        nvlp
  69                    Address of a pointer to nvlist_t.
  70 
  71 
  72        nvflag
  73                    Specify bit fields defining nvlist properties:
  74 
  75                    NV_UNIQUE_NAME
  76                                           The nvpair names are unique.
  77 
  78 
  79                    NV_UNIQUE_NAME_TYPE
  80                                           Name-data type combination is
  81                                           unique.
  82 
  83 
  84 
  85        flag
  86                    Specify 0. Reserved for future use.
  87 
  88 
  89        nvl
  90                    The nvlist_t to be processed.
  91 
  92 
  93        dst
  94                    The destination nvlist_t.
  95 
  96 
  97        size
  98                    Pointer to buffer to contain the encoded size.
  99 
 100 
 101        bufp
 102                    Address of buffer to pack nvlist into. Must be 8-byte
 103                    aligned. If NULL, library will allocate memory.
 104 
 105 
 106        buf
 107                    Buffer containing packed nvlist.
 108 
 109 
 110        buflen
 111                    Size of buffer bufp or buf points to.
 112 
 113 
 114        encoding
 115                    Encoding method for packing.
 116 
 117 
 118        nvo
 119                    Pluggable allocator operations pointer (nv_alloc_ops_t).
 120 
 121 
 122        nva
 123                    A pointer to an nv_alloc_t structure to be used for the
 124                    specified nvlist_t.
 125 
 126 
 127 DESCRIPTION
 128    List Manipulation
 129        The nvlist_alloc() function allocates a new name-value pair list and
 130        updates nvlp to point to the handle. The nvflag argument specifies
 131        nvlist properties to remain persistent across packing, unpacking, and
 132        duplication. If NV_UNIQUE_NAME was specified for nvflag, existing
 133        nvpairs with matching names are removed before the new nvpair is added.
 134        If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing nvpairs with
 135        matching names and data types are removed before the new nvpair is
 136        added. See nvlist_add_byte(3NVPAIR) for more information.
 137 
 138 
 139        The nvlist_xalloc() function is identical to nvlist_alloc() except that
 140        nvlist_xalloc() can use a different allocator, as described in the
 141        Pluggable Allocators section.
 142 
 143 
 144        The nvlist_free() function frees a name-value pair list. If nvl is a
 145        null pointer, no action occurs.
 146 
 147 
 148        The nvlist_size() function returns the minimum size of a contiguous
 149        buffer large enough to pack nvl. The encoding parameter specifies the
 150        method of encoding when packing nvl. Supported encoding methods are:
 151 
 152        NV_ENCODE_NATIVE
 153                            Straight bcopy() as described in bcopy(3C).
 154 
 155 
 156        NV_ENCODE_XDR
 157                            Use XDR encoding, suitable for sending to another
 158                            host.
 159 
 160 
 161 
 162        The nvlist_pack() function packs nvl into contiguous memory starting at
 163        *bufp. The encoding parameter specifies the method of encoding (see
 164        above).
 165 
 166            o      If *bufp is not NULL, *bufp is expected to be a caller-
 167                   allocated buffer of size *buflen.
 168 
 169            o      If *bufp is NULL, the library will allocate memory and
 170                   update *bufp to point to the memory and update *buflen to
 171                   contain the size of the allocated memory.
 172 
 173 
 174        The nvlist_xpack() function is identical to nvlist_pack() except that
 175        nvlist_xpack() can use a different allocator.
 176 
 177 
 178        The nvlist_unpack() function takes a buffer with a packed nvlist_t and
 179        unpacks it into a searchable nvlist_t. The library allocates memory for
 180        nvlist_t. The caller is responsible for freeing the memory by calling
 181        nvlist_free().
 182 
 183 
 184        The nvlist_xunpack() function is identical to nvlist_unpack() except
 185        that nvlist_xunpack() can use a different allocator.
 186 
 187 
 188        The nvlist_dup() function makes a copy of nvl and updates nvlp to point
 189        to the copy.
 190 
 191 
 192        The nvlist_xdup() function is identical to nvlist_dup() except that
 193        nvlist_xdup() can use a different allocator.
 194 
 195 
 196        The nvlist_merge() function adds copies of all name-value pairs from
 197        nvl to dst.  Name-value pairs in dst are replaced with name-value pairs
 198        from nvl that have identical names (if dst has the type NV_UNIQUE_NAME)
 199        or identical names and types (if dst has the type NV_UNIQUE_NAME_TYPE).
 200 
 201 
 202        The nvlist_lookup_nv_alloc() function retrieves the pointer to the
 203        allocator that was used when manipulating a name-value pair list.
 204 
 205    Pluggable Allocators
 206    Using Pluggable Allocators
 207        The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions
 208        provide an interface to specify the allocator to be used when
 209        manipulating a name-value pair list.
 210 
 211 
 212        The nv_alloc_init() function determines the allocator properties and
 213        puts them into the nva argument. The application must specify the
 214        nv_arg and nvo arguments and an optional variable argument list. The
 215        optional arguments are passed to the (*nv_ao_init()) function.
 216 
 217 
 218        The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(),
 219        nvlist_xunpack() and nvlist_xdup().
 220 
 221 
 222        The nv_alloc_reset() function is responsible for resetting the
 223        allocator properties to the data specified by nv_alloc_init(). When no
 224        (*nv_ao_reset()) function is specified, nv_alloc_reset() has no effect.
 225 
 226 
 227        The nv_alloc_fini() function destroys the allocator properties
 228        determined by nv_alloc_init(). When a (*nv_ao_fini()) function is
 229        specified, it is called from nv_alloc_fini().
 230 
 231 
 232        The disposition of the allocated objects and the memory used to store
 233        them is left to the allocator implementation.
 234 
 235 
 236        The nv_alloc_nosleep nv_alloc_t can be used with nvlist_xalloc() to
 237        mimic the behavior of nvlist_alloc().
 238 
 239 
 240        The nvpair allocator framework provides a pointer to the operation
 241        structure of a fixed buffer allocator. This allocator, nv_fixed_ops,
 242        uses a pre-allocated buffer for memory allocations. It is intended
 243        primarily for kernel use and is described on nvlist_alloc(9F).
 244 
 245 
 246        An example program that uses the pluggable allocator functionality is
 247        provided on nvlist_alloc(9F).
 248 
 249    Creating Pluggable Allocators
 250        Any producer of name-value pairs can specify its own allocator
 251        functions. The application must provide the following pluggable
 252        allocator operations:
 253 
 254          int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
 255          void (*nv_ao_fini)(nv_alloc_t *nva);
 256          void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
 257          void (*nv_ao_reset)(nv_alloc_t *nva);
 258          void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
 259 
 260 
 261 
 262        The nva argument of the allocator implementation is always the first
 263        argument.
 264 
 265 
 266        The optional (*nv_ao_init()) function is responsible for filling the
 267        data specified by nv_alloc_init() into the nva_arg argument.  The
 268        (*nv_ao_init()) function is only called when nv_alloc_init() is
 269        executed.
 270 
 271 
 272        The optional (*nv_ao_fini()) function is responsible for the cleanup of
 273        the allocator implementation. It is called by nv_alloc_fini().
 274 
 275 
 276        The required (*nv_ao_alloc()) function is used in the nvpair allocation
 277        framework for memory allocation. The sz argument specifies the size of
 278        the requested buffer.
 279 
 280 
 281        The optional (*nv_ao_reset()) function is responsible for resetting the
 282        nva_arg argument to the data specified by nv_alloc_init().
 283 
 284 
 285        The required (*nv_ao_free()) function is used in the nvpair allocator
 286        framework for memory deallocation. The buf argument is a pointer to a
 287        block previously allocated by the (*nv_ao_alloc()) function. The size
 288        argument sz must exactly match the original allocation.
 289 
 290 
 291        The disposition of the allocated objects and the memory used to store
 292        them is left to the allocator implementation.
 293 
 294 RETURN VALUES
 295        These functions return 0 on success and an error value on failure.
 296 
 297 
 298        The nvlist_lookup_nv_alloc() function returns a pointer to an
 299        allocator.
 300 
 301 ERRORS
 302        These functions will fail if:
 303 
 304        EINVAL
 305                  There is an invalid argument.
 306 
 307 
 308 
 309        The nvlist_alloc(), nvlist_dup(), nvlist_pack(), nvlist_unpack(),
 310        nvlist_merge(), nvlist_xalloc(), nvlist_xdup(), nvlist_xpack(), and
 311        nvlist_xunpack() functions will fail if:
 312 
 313        ENOMEM
 314                  There is insufficient memory.
 315 
 316 
 317 
 318        The nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and
 319        nvlist_xunpack() functions will fail if:
 320 
 321        EFAULT
 322                   An encode/decode error occurs.
 323 
 324 
 325        ENOTSUP
 326                   An encode/decode method is not supported.
 327 
 328 
 329 EXAMPLES
 330          /*
 331           * Program to create an nvlist.
 332           */
 333          #include <stdio.h>
 334          #include <sys/types.h>
 335          #include <string.h>
 336          #include <libnvpair.h>
 337 
 338          /* generate a packed nvlist */
 339          static int
 340          create_packed_nvlist(char **buf, uint_t *buflen, int encode)
 341          {
 342              uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
 343              int32_t int32[] = {3, 4, 5};
 344              char *strs[] = {"child0", "child1", "child2"};
 345              int err;
 346              nvlist_t *nvl;
 347 
 348              err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0);    /*     allocate list */
 349              if (err) {
 350                  (void) printf("nvlist_alloc() failed\n");
 351                  return (err);
 352              }
 353 
 354              /* add a value of some types */
 355              if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) ||
 356                  (nvlist_add_int32(nvl, "int32", int32[0]) != 0) ||
 357                  (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) ||
 358                  (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) {
 359                  nvlist_free(nvl);
 360                  return (-1);
 361              }
 362 
 363              err = nvlist_size(nvl, buflen, encode);
 364              if (err) {
 365                  (void) printf("nvlist_size: %s\n", strerror(err));
 366                  nvlist_free(nvl);
 367                  return (err);
 368              }
 369 
 370              /* pack into contig. memory */
 371              err = nvlist_pack(nvl, buf, buflen, encode, 0);
 372              if (err)
 373                  (void) printf("nvlist_pack: %s\n", strerror(err));
 374 
 375              /* free the original list */
 376              nvlist_free(nvl);
 377              return (err);
 378          }
 379 
 380          /* selectively print nvpairs */
 381          static void
 382          nvlist_lookup_and_print(nvlist_t *nvl)
 383          {
 384              char **str_val;
 385              int i, int_val;
 386              uint_t nval;
 387 
 388              if (nvlist_lookup_int32(nvl, "int32", &int_val) ==     0)
 389                  (void) printf("int32 = %d\n", int_val);
 390              if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval)
 391                  == 0) {
 392                      (void) printf("string_array =");
 393                      for (i = 0; i < nval; i++)
 394                              (void) printf(" %s", str_val[i]);
 395                      (void) printf("\n");
 396              }
 397          }
 398 
 399          /*ARGSUSED*/
 400          int
 401          main(int argc, char *argv[])
 402          {
 403              int err;
 404              char *buf = NULL;
 405              size_t buflen;
 406              nvlist_t *nvl = NULL;
 407 
 408              if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
 409                  (void) printf("cannot create packed nvlist buffer\n");
 410                  return(-1);
 411                  }
 412 
 413              /* unpack into an nvlist_t */
 414              err = nvlist_unpack(buf, buflen, &nvl, 0);
 415              if (err) {
 416                  (void) printf("nvlist_unpack(): %s\n", strerror(err));
 417                  return(-1);
 418              }
 419 
 420              /* selectively print out attributes */
 421              nvlist_lookup_and_print(nvl);
 422              return(0);
 423          }
 424 
 425 
 426 ATTRIBUTES
 427        See attributes(5) for descriptions of the following attributes:
 428 
 429 
 430 
 431 
 432        +--------------------+-----------------+
 433        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
 434        +--------------------+-----------------+
 435        |Interface Stability | Evolving        |
 436        +--------------------+-----------------+
 437        |MT-Level            | MT-Safe         |
 438        +--------------------+-----------------+
 439 
 440 SEE ALSO
 441        libnvpair(3LIB), attributes(5), nvlist_alloc(9F)
 442 
 443 
 444 
 445                                February 15, 2016         NVLIST_ALLOC(3NVPAIR)