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)