usr/src/man/man3nvpair/nvlist_alloc.3nvpair

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