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 2, 2004"
   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.
 247 .sp
 248 .LP
 249 The \fBnvlist_size()\fR function returns the minimum size of a contiguous
 250 buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
 251 the method of encoding when packing \fInvl\fR. Supported encoding methods are:
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBNV_ENCODE_NATIVE\fR\fR
 256 .ad
 257 .RS 20n
 258 Straight \fBbcopy()\fR as described in \fBbcopy\fR(3C).
 259 .RE
 260 
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBNV_ENCODE_XDR\fR\fR
 265 .ad
 266 .RS 20n
 267 Use XDR encoding, suitable for sending to another host.
 268 .RE
 269 
 270 .sp
 271 .LP
 272 The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
 273 starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
 274 encoding (see above).
 275 .RS +4
 276 .TP
 277 .ie t \(bu
 278 .el o
 279 If *\fIbufp\fR is not \fINULL\fR, *\fIbufp\fR is expected to be a
 280 caller-allocated buffer of size *\fIbuflen\fR.
 281 .RE
 282 .RS +4
 283 .TP
 284 .ie t \(bu
 285 .el o
 286 If *\fIbufp\fR is \fINULL\fR, the library will allocate memory and update
 287 *\fIbufp\fR to point to the memory and update *\fIbuflen\fR to contain the size
 288 of the allocated memory.
 289 .RE
 290 .sp
 291 .LP
 292 The \fBnvlist_xpack()\fR function is identical to \fBnvlist_pack()\fR except
 293 that \fBnvlist_xpack()\fR can use a different allocator.
 294 .sp
 295 .LP
 296 The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
 297 and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
 298 for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
 299 \fBnvlist_free()\fR.
 300 .sp
 301 .LP
 302 The \fBnvlist_xunpack()\fR function is identical to \fBnvlist_unpack()\fR
 303 except that \fBnvlist_xunpack()\fR can use a different allocator.
 304 .sp
 305 .LP
 306 The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
 307 \fInvlp\fR to point to the copy.
 308 .sp
 309 .LP
 310 The \fBnvlist_xdup()\fR function is identical to \fBnvlist_dup()\fR except that
 311 \fBnvlist_xdup()\fR can use a different allocator.
 312 .sp
 313 .LP
 314 The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
 315 \fInvl\fR to \fIdst\fR.  Name-value pairs in \fIdst\fR are replaced with
 316 name-value pairs from \fInvl\fR that have identical names (if \fIdst\fR has the
 317 type \fBNV_UNIQUE_NAME\fR) or identical names and types (if \fIdst\fR has the
 318 type \fBNV_UNIQUE_NAME_TYPE\fR).
 319 .sp
 320 .LP
 321 The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
 322 allocator that was used when manipulating a name-value pair list.
 323 .SS "Pluggable Allocators"
 324 .SS "Using Pluggable Allocators"
 325 .sp
 326 .LP
 327 The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
 328 functions provide an interface to specify the allocator to be used when
 329 manipulating a name-value pair list.
 330 .sp
 331 .LP
 332 The \fBnv_alloc_init()\fR function determines the allocator properties and puts
 333 them into the \fInva\fR argument. The application must specify the \fInv_arg\fR
 334 and \fInvo\fR arguments and an optional variable argument list. The optional
 335 arguments are passed to the (*\fBnv_ao_init()\fR) function.
 336 .sp
 337 .LP
 338 The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
 339 \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
 340 .sp
 341 .LP
 342 The \fBnv_alloc_reset()\fR function is responsible for resetting the allocator
 343 properties to the data specified by \fBnv_alloc_init()\fR. When no
 344 (*\fBnv_ao_reset()\fR) function is specified, \fBnv_alloc_reset()\fR has no
 345 effect.
 346 .sp
 347 .LP
 348 The \fBnv_alloc_fini()\fR function destroys the allocator properties determined
 349 by \fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) function is specified,
 350 it is called from \fBnv_alloc_fini()\fR.
 351 .sp
 352 .LP
 353 The disposition of the allocated objects and the memory used to store them is
 354 left to the allocator implementation.
 355 .sp
 356 .LP
 357 The \fBnv_alloc_nosleep\fR \fBnv_alloc_t\fR can be used with
 358 \fBnvlist_xalloc()\fR to mimic the behavior of \fBnvlist_alloc()\fR.
 359 .sp
 360 .LP
 361 The nvpair allocator framework provides a pointer to the operation structure of
 362 a fixed buffer allocator. This allocator, \fBnv_fixed_ops\fR, uses a
 363 pre-allocated buffer for memory allocations. It is intended primarily for
 364 kernel use and is described on \fBnvlist_alloc\fR(9F).
 365 .sp
 366 .LP
 367 An example program that uses the pluggable allocator functionality is provided
 368 on \fBnvlist_alloc\fR(9F).
 369 .SS "Creating Pluggable Allocators"
 370 .sp
 371 .LP
 372 Any producer of name-value pairs can specify its own allocator functions. The
 373 application must provide the following pluggable allocator operations:
 374 .sp
 375 .in +2
 376 .nf
 377 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
 378 void (*nv_ao_fini)(nv_alloc_t *nva);
 379 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
 380 void (*nv_ao_reset)(nv_alloc_t *nva);
 381 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
 382 .fi
 383 .in -2
 384 
 385 .sp
 386 .LP
 387 The \fInva\fR argument of the allocator implementation is always the first
 388 argument.
 389 .sp
 390 .LP
 391 The optional (*\fBnv_ao_init()\fR) function is responsible for filling the data
 392 specified by \fBnv_alloc_init()\fR into the \fInva_arg\fR argument.  The
 393 (*\fBnv_ao_init()\fR) function is only called when \fBnv_alloc_init()\fR is
 394 executed.
 395 .sp
 396 .LP
 397 The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
 398 the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
 399 .sp
 400 .LP
 401 The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
 402 framework for memory allocation. The \fIsz\fR argument specifies the size of
 403 the requested buffer.
 404 .sp
 405 .LP
 406 The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
 407 \fInva_arg\fR argument to the data specified by \fBnv_alloc_init()\fR.
 408 .sp
 409 .LP
 410 The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
 411 framework for memory deallocation. The \fIbuf\fR argument is a pointer to a
 412 block previously allocated by the (*\fBnv_ao_alloc()\fR) function. The size
 413 argument \fIsz\fR must exactly match the original allocation.
 414 .sp
 415 .LP
 416 The disposition of the allocated objects and the memory used to store them is
 417 left to the allocator implementation.
 418 .SH RETURN VALUES
 419 .sp
 420 .LP
 421 These functions return 0 on success and an error value on failure.
 422 .sp
 423 .LP
 424 The \fBnvlist_lookup_nv_alloc()\fR function returns a pointer to an allocator.
 425 .SH ERRORS
 426 .sp
 427 .LP
 428 These functions will fail if:
 429 .sp
 430 .ne 2
 431 .na
 432 \fB\fBEINVAL\fR\fR
 433 .ad
 434 .RS 10n
 435 There is an invalid argument.
 436 .RE
 437 
 438 .sp
 439 .LP
 440 The \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_pack()\fR,
 441 \fBnvlist_unpack()\fR, \fBnvlist_merge()\fR, \fBnvlist_xalloc()\fR,
 442 \fBnvlist_xdup()\fR, \fBnvlist_xpack()\fR, and \fBnvlist_xunpack()\fR functions
 443 will fail if:
 444 .sp
 445 .ne 2
 446 .na
 447 \fB\fBENOMEM\fR\fR
 448 .ad
 449 .RS 10n
 450 There is insufficient memory.
 451 .RE
 452 
 453 .sp
 454 .LP
 455 The \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
 456 \fBnvlist_xunpack()\fR functions will fail if:
 457 .sp
 458 .ne 2
 459 .na
 460 \fB\fBEFAULT\fR\fR
 461 .ad
 462 .RS 11n
 463 An encode/decode error occurs.
 464 .RE
 465 
 466 .sp
 467 .ne 2
 468 .na
 469 \fB\fBENOTSUP\fR\fR
 470 .ad
 471 .RS 11n
 472 An encode/decode method is not supported.
 473 .RE
 474 
 475 .SH EXAMPLES
 476 .sp
 477 .in +2
 478 .nf
 479 /*
 480  * Program to create an nvlist.
 481  */
 482 #include <stdio.h>
 483 #include <sys/types.h>
 484 #include <string.h>
 485 #include <libnvpair.h>
 486 
 487 /* generate a packed nvlist */
 488 static int
 489 create_packed_nvlist(char **buf, uint_t *buflen, int encode)
 490 {
 491     uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
 492     int32_t int32[] = {3, 4, 5};
 493     char *strs[] = {"child0", "child1", "child2"};
 494     int err;
 495     nvlist_t *nvl;
 496 
 497     err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0);    /* allocate list */
 498     if (err) {
 499         (void) printf("nvlist_alloc() failed\en");
 500         return (err);
 501     }
 502 
 503     /* add a value of some types */
 504     if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) ||
 505         (nvlist_add_int32(nvl, "int32", int32[0]) != 0) ||
 506         (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) ||
 507         (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) {
 508         nvlist_free(nvl);
 509         return (-1);
 510     }
 511 
 512     err = nvlist_size(nvl, buflen, encode);
 513     if (err) {
 514         (void) printf("nvlist_size: %s\en", strerror(err));
 515         nvlist_free(nvl);
 516         return (err);
 517     }
 518 
 519     /* pack into contig. memory */
 520     err = nvlist_pack(nvl, buf, buflen, encode, 0);
 521     if (err)
 522         (void) printf("nvlist_pack: %s\en", strerror(err));
 523 
 524     /* free the original list */
 525     nvlist_free(nvl);
 526     return (err);
 527 }
 528 
 529 /* selectively print nvpairs */
 530 static void
 531 nvlist_lookup_and_print(nvlist_t *nvl)
 532 {
 533     char **str_val;
 534     int i, int_val;
 535     uint_t nval;
 536 
 537     if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0)
 538         (void) printf("int32 = %d\en", int_val);
 539     if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval)
 540         == 0) {
 541             (void) printf("string_array =");
 542             for (i = 0; i < nval; i++)
 543                     (void) printf(" %s", str_val[i]);
 544             (void) printf("\en");
 545     }
 546 }
 547 
 548 /*ARGSUSED*/
 549 int
 550 main(int argc, char *argv[])
 551 {
 552     int err;
 553     char *buf = NULL;
 554     size_t buflen;
 555     nvlist_t *nvl = NULL;
 556 
 557     if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
 558         (void) printf("cannot create packed nvlist buffer\en");
 559         return(-1);
 560         }
 561 
 562     /* unpack into an nvlist_t */
 563     err = nvlist_unpack(buf, buflen, &nvl, 0);
 564     if (err) {
 565         (void) printf("nvlist_unpack(): %s\en", strerror(err));
 566         return(-1);
 567     }
 568 
 569     /* selectively print out attributes */
 570     nvlist_lookup_and_print(nvl);
 571     return(0);
 572 }
 573 .fi
 574 .in -2
 575 
 576 .SH ATTRIBUTES
 577 .sp
 578 .LP
 579 See \fBattributes\fR(5) for descriptions of the following attributes:
 580 .sp
 581 
 582 .sp
 583 .TS
 584 box;
 585 c | c
 586 l | l .
 587 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 588 _
 589 Interface Stability     Evolving
 590 _
 591 MT-Level        MT-Safe
 592 .TE
 593 
 594 .SH SEE ALSO
 595 .sp
 596 .LP
 597 \fBlibnvpair\fR(3LIB), \fBattributes\fR(5), \fBnvlist_alloc\fR(9F)