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)