1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH NVLIST_ALLOC 3NVPAIR "Feb 15, 2016"
   7 .SH NAME
   8 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup,
   9 nvlist_merge, nvlist_xalloc, nvlist_xpack, nvlist_xunpack, nvlist_xdup,
  10 nvlist_lookup_nv_alloc, nv_alloc_init, nv_alloc_reset, nv_alloc_fini \- manage
  11 a name-value pair list
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnvpair\fR [ \fIlibrary\fR... ]
  16 #include <libnvpair.h>
  17 
  18 \fBint\fR \fBnvlist_alloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, \fBint\fR \fIflag\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBnvlist_xalloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR,
  24      \fBnv_alloc_t *\fR \fInva\fR);
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBnvlist_free\fR(\fBnvlist_t *\fR\fInvl\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBint\fR \fBnvlist_size\fR(\fBnvlist_t *\fR\fInvl\fR, \fBsize_t *\fR\fIsize\fR, \fBint\fR \fIencoding\fR);
  35 .fi
  36 
  37 .LP
  38 .nf
  39 \fBint\fR \fBnvlist_pack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR,
  40      \fBint\fR \fIencoding\fR, \fBint\fR \fIflag\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBint\fR \fBnvlist_xpack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR,
  46      \fBint\fR \fIencoding\fR, \fBnv_alloc_t *\fR \fInva\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBint\fR \fBnvlist_unpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR,
  52      \fBint\fR \fIflag\fR);
  53 .fi
  54 
  55 .LP
  56 .nf
  57 \fBint\fR \fBnvlist_xunpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR,
  58      \fBnv_alloc_t *\fR \fInva\fR);
  59 .fi
  60 
  61 .LP
  62 .nf
  63 \fBint\fR \fBnvlist_dup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
  64 .fi
  65 
  66 .LP
  67 .nf
  68 \fBint\fR \fBnvlist_xdup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR,
  69      \fBnv_alloc_t *\fR \fInva\fR);
  70 .fi
  71 
  72 .LP
  73 .nf
  74 \fBint\fR \fBnvlist_merge\fR(\fBnvlist_t *\fR\fIdst\fR, \fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag\fR);
  75 .fi
  76 
  77 .LP
  78 .nf
  79 \fBnv_alloc_t *\fR \fBnvlist_lookup_nv_alloc\fR(\fBnvlist_t *\fR\fInvl\fR);
  80 .fi
  81 
  82 .LP
  83 .nf
  84 \fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR, \fBconst nv_alloc_ops_t *\fR\fInvo\fR,
  85      \fB/*\fR \fIargs\fR */ ...);
  86 .fi
  87 
  88 .LP
  89 .nf
  90 \fBvoid\fR \fBnv_alloc_reset\fR(\fBnv_alloc_t *\fR\fInva\fR);
  91 .fi
  92 
  93 .LP
  94 .nf
  95 \fBvoid\fR \fBnv_alloc_fini\fR(\fBnv_alloc_t *\fR\fInva\fR);
  96 .fi
  97 
  98 .SH PARAMETERS
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fInvlp\fR\fR
 103 .ad
 104 .RS 12n
 105 Address of a pointer to \fBnvlist_t\fR.
 106 .RE
 107 
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fInvflag\fR\fR
 112 .ad
 113 .RS 12n
 114 Specify bit fields defining \fBnvlist\fR properties:
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBNV_UNIQUE_NAME\fR\fR
 119 .ad
 120 .RS 23n
 121 The \fBnvpair\fR names are unique.
 122 .RE
 123 
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBNV_UNIQUE_NAME_TYPE\fR\fR
 128 .ad
 129 .RS 23n
 130 Name-data type combination is unique.
 131 .RE
 132 
 133 .RE
 134 
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fIflag\fR\fR
 139 .ad
 140 .RS 12n
 141 Specify 0. Reserved for future use.
 142 .RE
 143 
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fInvl\fR\fR
 148 .ad
 149 .RS 12n
 150 The \fBnvlist_t\fR to be processed.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fIdst\fR\fR
 157 .ad
 158 .RS 12n
 159 The destination \fBnvlist_t\fR.
 160 .RE
 161 
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fIsize\fR\fR
 166 .ad
 167 .RS 12n
 168 Pointer to buffer to contain the encoded size.
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fIbufp\fR\fR
 175 .ad
 176 .RS 12n
 177 Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If
 178 \fINULL\fR, library will allocate memory.
 179 .RE
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fIbuf\fR\fR
 185 .ad
 186 .RS 12n
 187 Buffer containing packed \fBnvlist\fR.
 188 .RE
 189 
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fIbuflen\fR\fR
 194 .ad
 195 .RS 12n
 196 Size of buffer \fIbufp\fR or \fIbuf\fR points to.
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fIencoding\fR\fR
 203 .ad
 204 .RS 12n
 205 Encoding method for packing.
 206 .RE
 207 
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fInvo\fR\fR
 212 .ad
 213 .RS 12n
 214 Pluggable allocator operations pointer (\fBnv_alloc_ops_t\fR).
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fInva\fR\fR
 221 .ad
 222 .RS 12n
 223 A pointer to an \fBnv_alloc_t\fR structure to be used for the specified
 224 \fBnvlist_t\fR.
 225 .RE
 226 
 227 .SH DESCRIPTION
 228 .SS "List Manipulation"
 229 .sp
 230 .LP
 231 The \fBnvlist_alloc()\fR function allocates a new name-value pair list and
 232 updates \fInvlp\fR to point to the handle. The \fInvflag\fR argument specifies
 233 \fBnvlist\fR properties to remain persistent across packing, unpacking, and
 234 duplication. If \fBNV_UNIQUE_NAME\fR was specified for \fInvflag\fR, existing
 235 nvpairs with matching names are removed before the new nvpair is added. If
 236 \fBNV_UNIQUE_NAME_TYPE\fR was specified for \fInvflag\fR, existing nvpairs with
 237 matching names and data types are removed before the new nvpair is added. See
 238 \fBnvlist_add_byte\fR(3NVPAIR) for more information.
 239 .sp
 240 .LP
 241 The \fBnvlist_xalloc()\fR function is identical to \fBnvlist_alloc()\fR except
 242 that \fBnvlist_xalloc()\fR can use a different allocator, as described in the
 243 Pluggable Allocators section.
 244 .sp
 245 .LP
 246 The \fBnvlist_free()\fR function frees a name-value pair list. If \fInvl\fR
 247 is a null pointer, no action occurs.
 248 .sp
 249 .LP
 250 The \fBnvlist_size()\fR function returns the minimum size of a contiguous
 251 buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
 252 the method of encoding when packing \fInvl\fR. Supported encoding methods are:
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBNV_ENCODE_NATIVE\fR\fR
 257 .ad
 258 .RS 20n
 259 Straight \fBbcopy()\fR as described in \fBbcopy\fR(3C).
 260 .RE
 261 
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBNV_ENCODE_XDR\fR\fR
 266 .ad
 267 .RS 20n
 268 Use XDR encoding, suitable for sending to another host.
 269 .RE
 270 
 271 .sp
 272 .LP
 273 The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
 274 starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
 275 encoding (see above).
 276 .RS +4
 277 .TP
 278 .ie t \(bu
 279 .el o
 280 If *\fIbufp\fR is not \fINULL\fR, *\fIbufp\fR is expected to be a
 281 caller-allocated buffer of size *\fIbuflen\fR.
 282 .RE
 283 .RS +4
 284 .TP
 285 .ie t \(bu
 286 .el o
 287 If *\fIbufp\fR is \fINULL\fR, the library will allocate memory and update
 288 *\fIbufp\fR to point to the memory and update *\fIbuflen\fR to contain the size
 289 of the allocated memory.
 290 .RE
 291 .sp
 292 .LP
 293 The \fBnvlist_xpack()\fR function is identical to \fBnvlist_pack()\fR except
 294 that \fBnvlist_xpack()\fR can use a different allocator.
 295 .sp
 296 .LP
 297 The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
 298 and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
 299 for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
 300 \fBnvlist_free()\fR.
 301 .sp
 302 .LP
 303 The \fBnvlist_xunpack()\fR function is identical to \fBnvlist_unpack()\fR
 304 except that \fBnvlist_xunpack()\fR can use a different allocator.
 305 .sp
 306 .LP
 307 The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
 308 \fInvlp\fR to point to the copy.
 309 .sp
 310 .LP
 311 The \fBnvlist_xdup()\fR function is identical to \fBnvlist_dup()\fR except that
 312 \fBnvlist_xdup()\fR can use a different allocator.
 313 .sp
 314 .LP
 315 The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
 316 \fInvl\fR to \fIdst\fR.  Name-value pairs in \fIdst\fR are replaced with
 317 name-value pairs from \fInvl\fR that have identical names (if \fIdst\fR has the
 318 type \fBNV_UNIQUE_NAME\fR) or identical names and types (if \fIdst\fR has the
 319 type \fBNV_UNIQUE_NAME_TYPE\fR).
 320 .sp
 321 .LP
 322 The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
 323 allocator that was used when manipulating a name-value pair list.
 324 .SS "Pluggable Allocators"
 325 .SS "Using Pluggable Allocators"
 326 .sp
 327 .LP
 328 The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
 329 functions provide an interface to specify the allocator to be used when
 330 manipulating a name-value pair list.
 331 .sp
 332 .LP
 333 The \fBnv_alloc_init()\fR function determines the allocator properties and puts
 334 them into the \fInva\fR argument. The application must specify the \fInv_arg\fR
 335 and \fInvo\fR arguments and an optional variable argument list. The optional
 336 arguments are passed to the (*\fBnv_ao_init()\fR) function.
 337 .sp
 338 .LP
 339 The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
 340 \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
 341 .sp
 342 .LP
 343 The \fBnv_alloc_reset()\fR function is responsible for resetting the allocator
 344 properties to the data specified by \fBnv_alloc_init()\fR. When no
 345 (*\fBnv_ao_reset()\fR) function is specified, \fBnv_alloc_reset()\fR has no
 346 effect.
 347 .sp
 348 .LP
 349 The \fBnv_alloc_fini()\fR function destroys the allocator properties determined
 350 by \fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) function is specified,
 351 it is called from \fBnv_alloc_fini()\fR.
 352 .sp
 353 .LP
 354 The disposition of the allocated objects and the memory used to store them is
 355 left to the allocator implementation.
 356 .sp
 357 .LP
 358 The \fBnv_alloc_nosleep\fR \fBnv_alloc_t\fR can be used with
 359 \fBnvlist_xalloc()\fR to mimic the behavior of \fBnvlist_alloc()\fR.
 360 .sp
 361 .LP
 362 The nvpair allocator framework provides a pointer to the operation structure of
 363 a fixed buffer allocator. This allocator, \fBnv_fixed_ops\fR, uses a
 364 pre-allocated buffer for memory allocations. It is intended primarily for
 365 kernel use and is described on \fBnvlist_alloc\fR(9F).
 366 .sp
 367 .LP
 368 An example program that uses the pluggable allocator functionality is provided
 369 on \fBnvlist_alloc\fR(9F).
 370 .SS "Creating Pluggable Allocators"
 371 .sp
 372 .LP
 373 Any producer of name-value pairs can specify its own allocator functions. The
 374 application must provide the following pluggable allocator operations:
 375 .sp
 376 .in +2
 377 .nf
 378 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
 379 void (*nv_ao_fini)(nv_alloc_t *nva);
 380 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
 381 void (*nv_ao_reset)(nv_alloc_t *nva);
 382 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
 383 .fi
 384 .in -2
 385 
 386 .sp
 387 .LP
 388 The \fInva\fR argument of the allocator implementation is always the first
 389 argument.
 390 .sp
 391 .LP
 392 The optional (*\fBnv_ao_init()\fR) function is responsible for filling the data
 393 specified by \fBnv_alloc_init()\fR into the \fInva_arg\fR argument.  The
 394 (*\fBnv_ao_init()\fR) function is only called when \fBnv_alloc_init()\fR is
 395 executed.
 396 .sp
 397 .LP
 398 The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
 399 the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
 400 .sp
 401 .LP
 402 The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
 403 framework for memory allocation. The \fIsz\fR argument specifies the size of
 404 the requested buffer.
 405 .sp
 406 .LP
 407 The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
 408 \fInva_arg\fR argument to the data specified by \fBnv_alloc_init()\fR.
 409 .sp
 410 .LP
 411 The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
 412 framework for memory deallocation. The \fIbuf\fR argument is a pointer to a
 413 block previously allocated by the (*\fBnv_ao_alloc()\fR) function. The size
 414 argument \fIsz\fR must exactly match the original allocation.
 415 .sp
 416 .LP
 417 The disposition of the allocated objects and the memory used to store them is
 418 left to the allocator implementation.
 419 .SH RETURN VALUES
 420 .sp
 421 .LP
 422 These functions return 0 on success and an error value on failure.
 423 .sp
 424 .LP
 425 The \fBnvlist_lookup_nv_alloc()\fR function returns a pointer to an allocator.
 426 .SH ERRORS
 427 .sp
 428 .LP
 429 These functions will fail if:
 430 .sp
 431 .ne 2
 432 .na
 433 \fB\fBEINVAL\fR\fR
 434 .ad
 435 .RS 10n
 436 There is an invalid argument.
 437 .RE
 438 
 439 .sp
 440 .LP
 441 The \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_pack()\fR,
 442 \fBnvlist_unpack()\fR, \fBnvlist_merge()\fR, \fBnvlist_xalloc()\fR,
 443 \fBnvlist_xdup()\fR, \fBnvlist_xpack()\fR, and \fBnvlist_xunpack()\fR functions
 444 will fail if:
 445 .sp
 446 .ne 2
 447 .na
 448 \fB\fBENOMEM\fR\fR
 449 .ad
 450 .RS 10n
 451 There is insufficient memory.
 452 .RE
 453 
 454 .sp
 455 .LP
 456 The \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
 457 \fBnvlist_xunpack()\fR functions will fail if:
 458 .sp
 459 .ne 2
 460 .na
 461 \fB\fBEFAULT\fR\fR
 462 .ad
 463 .RS 11n
 464 An encode/decode error occurs.
 465 .RE
 466 
 467 .sp
 468 .ne 2
 469 .na
 470 \fB\fBENOTSUP\fR\fR
 471 .ad
 472 .RS 11n
 473 An encode/decode method is not supported.
 474 .RE
 475 
 476 .SH EXAMPLES
 477 .sp
 478 .in +2
 479 .nf
 480 /*
 481  * Program to create an nvlist.
 482  */
 483 #include <stdio.h>
 484 #include <sys/types.h>
 485 #include <string.h>
 486 #include <libnvpair.h>
 487 
 488 /* generate a packed nvlist */
 489 static int
 490 create_packed_nvlist(char **buf, uint_t *buflen, int encode)
 491 {
 492     uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
 493     int32_t int32[] = {3, 4, 5};
 494     char *strs[] = {"child0", "child1", "child2"};
 495     int err;
 496     nvlist_t *nvl;
 497 
 498     err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0);    /* allocate list */
 499     if (err) {
 500         (void) printf("nvlist_alloc() failed\en");
 501         return (err);
 502     }
 503 
 504     /* add a value of some types */
 505     if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) ||
 506         (nvlist_add_int32(nvl, "int32", int32[0]) != 0) ||
 507         (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) ||
 508         (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) {
 509         nvlist_free(nvl);
 510         return (-1);
 511     }
 512 
 513     err = nvlist_size(nvl, buflen, encode);
 514     if (err) {
 515         (void) printf("nvlist_size: %s\en", strerror(err));
 516         nvlist_free(nvl);
 517         return (err);
 518     }
 519 
 520     /* pack into contig. memory */
 521     err = nvlist_pack(nvl, buf, buflen, encode, 0);
 522     if (err)
 523         (void) printf("nvlist_pack: %s\en", strerror(err));
 524 
 525     /* free the original list */
 526     nvlist_free(nvl);
 527     return (err);
 528 }
 529 
 530 /* selectively print nvpairs */
 531 static void
 532 nvlist_lookup_and_print(nvlist_t *nvl)
 533 {
 534     char **str_val;
 535     int i, int_val;
 536     uint_t nval;
 537 
 538     if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0)
 539         (void) printf("int32 = %d\en", int_val);
 540     if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval)
 541         == 0) {
 542             (void) printf("string_array =");
 543             for (i = 0; i < nval; i++)
 544                     (void) printf(" %s", str_val[i]);
 545             (void) printf("\en");
 546     }
 547 }
 548 
 549 /*ARGSUSED*/
 550 int
 551 main(int argc, char *argv[])
 552 {
 553     int err;
 554     char *buf = NULL;
 555     size_t buflen;
 556     nvlist_t *nvl = NULL;
 557 
 558     if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
 559         (void) printf("cannot create packed nvlist buffer\en");
 560         return(-1);
 561         }
 562 
 563     /* unpack into an nvlist_t */
 564     err = nvlist_unpack(buf, buflen, &nvl, 0);
 565     if (err) {
 566         (void) printf("nvlist_unpack(): %s\en", strerror(err));
 567         return(-1);
 568     }
 569 
 570     /* selectively print out attributes */
 571     nvlist_lookup_and_print(nvl);
 572     return(0);
 573 }
 574 .fi
 575 .in -2
 576 
 577 .SH ATTRIBUTES
 578 .sp
 579 .LP
 580 See \fBattributes\fR(5) for descriptions of the following attributes:
 581 .sp
 582 
 583 .sp
 584 .TS
 585 box;
 586 c | c
 587 l | l .
 588 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 589 _
 590 Interface Stability     Evolving
 591 _
 592 MT-Level        MT-Safe
 593 .TE
 594 
 595 .SH SEE ALSO
 596 .sp
 597 .LP
 598 \fBlibnvpair\fR(3LIB), \fBattributes\fR(5), \fBnvlist_alloc\fR(9F)