1 NVLIST_ALLOC(3NVPAIR) Name-value Pair Library Functions NVLIST_ALLOC(3NVPAIR) 2 3 4 5 NAME 6 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, 7 nvlist_dup, nvlist_merge, nvlist_xalloc, nvlist_xpack, nvlist_xunpack, 8 nvlist_xdup, nvlist_lookup_nv_alloc, nv_alloc_init, nv_alloc_reset, 9 nv_alloc_fini - manage a name-value pair list 10 11 SYNOPSIS 12 cc [ flag... ] file... -lnvpair [ library... ] 13 #include <libnvpair.h> 14 15 int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag); 16 17 18 int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, 19 nv_alloc_t * nva); 20 21 22 void nvlist_free(nvlist_t *nvl); 23 24 25 int nvlist_size(nvlist_t *nvl, size_t *size, int encoding); 26 27 28 int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, 29 int encoding, int flag); 30 31 32 int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, 33 int encoding, nv_alloc_t * nva); 34 35 36 int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, 37 int flag); 38 39 40 int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp, 41 nv_alloc_t * nva); 42 43 44 int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag); 45 46 47 int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp, 48 nv_alloc_t * nva); 49 50 51 int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag); 52 53 54 nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl); 55 56 57 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo, 58 /* args */ ...); 59 60 61 void nv_alloc_reset(nv_alloc_t *nva); 62 63 64 void nv_alloc_fini(nv_alloc_t *nva); 65 66 67 PARAMETERS 68 nvlp 69 Address of a pointer to nvlist_t. 70 71 72 nvflag 73 Specify bit fields defining nvlist properties: 74 75 NV_UNIQUE_NAME 76 The nvpair names are unique. 77 78 79 NV_UNIQUE_NAME_TYPE 80 Name-data type combination is 81 unique. 82 83 84 85 flag 86 Specify 0. Reserved for future use. 87 88 89 nvl 90 The nvlist_t to be processed. 91 92 93 dst 94 The destination nvlist_t. 95 96 97 size 98 Pointer to buffer to contain the encoded size. 99 100 101 bufp 102 Address of buffer to pack nvlist into. Must be 8-byte 103 aligned. If NULL, library will allocate memory. 104 105 106 buf 107 Buffer containing packed nvlist. 108 109 110 buflen 111 Size of buffer bufp or buf points to. 112 113 114 encoding 115 Encoding method for packing. 116 117 118 nvo 119 Pluggable allocator operations pointer (nv_alloc_ops_t). 120 121 122 nva 123 A pointer to an nv_alloc_t structure to be used for the 124 specified nvlist_t. 125 126 127 DESCRIPTION 128 List Manipulation 129 The nvlist_alloc() function allocates a new name-value pair list and 130 updates nvlp to point to the handle. The nvflag argument specifies 131 nvlist properties to remain persistent across packing, unpacking, and 132 duplication. If NV_UNIQUE_NAME was specified for nvflag, existing 133 nvpairs with matching names are removed before the new nvpair is added. 134 If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing nvpairs with 135 matching names and data types are removed before the new nvpair is 136 added. See nvlist_add_byte(3NVPAIR) for more information. 137 138 139 The nvlist_xalloc() function is identical to nvlist_alloc() except that 140 nvlist_xalloc() can use a different allocator, as described in the 141 Pluggable Allocators section. 142 143 144 The nvlist_free() function frees a name-value pair list. If nvl is a 145 null pointer, no action occurs. 146 147 148 The nvlist_size() function returns the minimum size of a contiguous 149 buffer large enough to pack nvl. The encoding parameter specifies the 150 method of encoding when packing nvl. Supported encoding methods are: 151 152 NV_ENCODE_NATIVE 153 Straight bcopy() as described in bcopy(3C). 154 155 156 NV_ENCODE_XDR 157 Use XDR encoding, suitable for sending to another 158 host. 159 160 161 162 The nvlist_pack() function packs nvl into contiguous memory starting at 163 *bufp. The encoding parameter specifies the method of encoding (see 164 above). 165 166 o If *bufp is not NULL, *bufp is expected to be a caller- 167 allocated buffer of size *buflen. 168 169 o If *bufp is NULL, the library will allocate memory and 170 update *bufp to point to the memory and update *buflen to 171 contain the size of the allocated memory. 172 173 174 The nvlist_xpack() function is identical to nvlist_pack() except that 175 nvlist_xpack() can use a different allocator. 176 177 178 The nvlist_unpack() function takes a buffer with a packed nvlist_t and 179 unpacks it into a searchable nvlist_t. The library allocates memory for 180 nvlist_t. The caller is responsible for freeing the memory by calling 181 nvlist_free(). 182 183 184 The nvlist_xunpack() function is identical to nvlist_unpack() except 185 that nvlist_xunpack() can use a different allocator. 186 187 188 The nvlist_dup() function makes a copy of nvl and updates nvlp to point 189 to the copy. 190 191 192 The nvlist_xdup() function is identical to nvlist_dup() except that 193 nvlist_xdup() can use a different allocator. 194 195 196 The nvlist_merge() function adds copies of all name-value pairs from 197 nvl to dst. Name-value pairs in dst are replaced with name-value pairs 198 from nvl that have identical names (if dst has the type NV_UNIQUE_NAME) 199 or identical names and types (if dst has the type NV_UNIQUE_NAME_TYPE). 200 201 202 The nvlist_lookup_nv_alloc() function retrieves the pointer to the 203 allocator that was used when manipulating a name-value pair list. 204 205 Pluggable Allocators 206 Using Pluggable Allocators 207 The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions 208 provide an interface to specify the allocator to be used when 209 manipulating a name-value pair list. 210 211 212 The nv_alloc_init() function determines the allocator properties and 213 puts them into the nva argument. The application must specify the 214 nv_arg and nvo arguments and an optional variable argument list. The 215 optional arguments are passed to the (*nv_ao_init()) function. 216 217 218 The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(), 219 nvlist_xunpack() and nvlist_xdup(). 220 221 222 The nv_alloc_reset() function is responsible for resetting the 223 allocator properties to the data specified by nv_alloc_init(). When no 224 (*nv_ao_reset()) function is specified, nv_alloc_reset() has no effect. 225 226 227 The nv_alloc_fini() function destroys the allocator properties 228 determined by nv_alloc_init(). When a (*nv_ao_fini()) function is 229 specified, it is called from nv_alloc_fini(). 230 231 232 The disposition of the allocated objects and the memory used to store 233 them is left to the allocator implementation. 234 235 236 The nv_alloc_nosleep nv_alloc_t can be used with nvlist_xalloc() to 237 mimic the behavior of nvlist_alloc(). 238 239 240 The nvpair allocator framework provides a pointer to the operation 241 structure of a fixed buffer allocator. This allocator, nv_fixed_ops, 242 uses a pre-allocated buffer for memory allocations. It is intended 243 primarily for kernel use and is described on nvlist_alloc(9F). 244 245 246 An example program that uses the pluggable allocator functionality is 247 provided on nvlist_alloc(9F). 248 249 Creating Pluggable Allocators 250 Any producer of name-value pairs can specify its own allocator 251 functions. The application must provide the following pluggable 252 allocator operations: 253 254 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist); 255 void (*nv_ao_fini)(nv_alloc_t *nva); 256 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz); 257 void (*nv_ao_reset)(nv_alloc_t *nva); 258 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz); 259 260 261 262 The nva argument of the allocator implementation is always the first 263 argument. 264 265 266 The optional (*nv_ao_init()) function is responsible for filling the 267 data specified by nv_alloc_init() into the nva_arg argument. The 268 (*nv_ao_init()) function is only called when nv_alloc_init() is 269 executed. 270 271 272 The optional (*nv_ao_fini()) function is responsible for the cleanup of 273 the allocator implementation. It is called by nv_alloc_fini(). 274 275 276 The required (*nv_ao_alloc()) function is used in the nvpair allocation 277 framework for memory allocation. The sz argument specifies the size of 278 the requested buffer. 279 280 281 The optional (*nv_ao_reset()) function is responsible for resetting the 282 nva_arg argument to the data specified by nv_alloc_init(). 283 284 285 The required (*nv_ao_free()) function is used in the nvpair allocator 286 framework for memory deallocation. The buf argument is a pointer to a 287 block previously allocated by the (*nv_ao_alloc()) function. The size 288 argument sz must exactly match the original allocation. 289 290 291 The disposition of the allocated objects and the memory used to store 292 them is left to the allocator implementation. 293 294 RETURN VALUES 295 These functions return 0 on success and an error value on failure. 296 297 298 The nvlist_lookup_nv_alloc() function returns a pointer to an 299 allocator. 300 301 ERRORS 302 These functions will fail if: 303 304 EINVAL 305 There is an invalid argument. 306 307 308 309 The nvlist_alloc(), nvlist_dup(), nvlist_pack(), nvlist_unpack(), 310 nvlist_merge(), nvlist_xalloc(), nvlist_xdup(), nvlist_xpack(), and 311 nvlist_xunpack() functions will fail if: 312 313 ENOMEM 314 There is insufficient memory. 315 316 317 318 The nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and 319 nvlist_xunpack() functions will fail if: 320 321 EFAULT 322 An encode/decode error occurs. 323 324 325 ENOTSUP 326 An encode/decode method is not supported. 327 328 329 EXAMPLES 330 /* 331 * Program to create an nvlist. 332 */ 333 #include <stdio.h> 334 #include <sys/types.h> 335 #include <string.h> 336 #include <libnvpair.h> 337 338 /* generate a packed nvlist */ 339 static int 340 create_packed_nvlist(char **buf, uint_t *buflen, int encode) 341 { 342 uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd}; 343 int32_t int32[] = {3, 4, 5}; 344 char *strs[] = {"child0", "child1", "child2"}; 345 int err; 346 nvlist_t *nvl; 347 348 err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0); /* allocate list */ 349 if (err) { 350 (void) printf("nvlist_alloc() failed\n"); 351 return (err); 352 } 353 354 /* add a value of some types */ 355 if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) || 356 (nvlist_add_int32(nvl, "int32", int32[0]) != 0) || 357 (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) || 358 (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) { 359 nvlist_free(nvl); 360 return (-1); 361 } 362 363 err = nvlist_size(nvl, buflen, encode); 364 if (err) { 365 (void) printf("nvlist_size: %s\n", strerror(err)); 366 nvlist_free(nvl); 367 return (err); 368 } 369 370 /* pack into contig. memory */ 371 err = nvlist_pack(nvl, buf, buflen, encode, 0); 372 if (err) 373 (void) printf("nvlist_pack: %s\n", strerror(err)); 374 375 /* free the original list */ 376 nvlist_free(nvl); 377 return (err); 378 } 379 380 /* selectively print nvpairs */ 381 static void 382 nvlist_lookup_and_print(nvlist_t *nvl) 383 { 384 char **str_val; 385 int i, int_val; 386 uint_t nval; 387 388 if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0) 389 (void) printf("int32 = %d\n", int_val); 390 if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval) 391 == 0) { 392 (void) printf("string_array ="); 393 for (i = 0; i < nval; i++) 394 (void) printf(" %s", str_val[i]); 395 (void) printf("\n"); 396 } 397 } 398 399 /*ARGSUSED*/ 400 int 401 main(int argc, char *argv[]) 402 { 403 int err; 404 char *buf = NULL; 405 size_t buflen; 406 nvlist_t *nvl = NULL; 407 408 if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) { 409 (void) printf("cannot create packed nvlist buffer\n"); 410 return(-1); 411 } 412 413 /* unpack into an nvlist_t */ 414 err = nvlist_unpack(buf, buflen, &nvl, 0); 415 if (err) { 416 (void) printf("nvlist_unpack(): %s\n", strerror(err)); 417 return(-1); 418 } 419 420 /* selectively print out attributes */ 421 nvlist_lookup_and_print(nvl); 422 return(0); 423 } 424 425 426 ATTRIBUTES 427 See attributes(5) for descriptions of the following attributes: 428 429 430 431 432 +--------------------+-----------------+ 433 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 434 +--------------------+-----------------+ 435 |Interface Stability | Evolving | 436 +--------------------+-----------------+ 437 |MT-Level | MT-Safe | 438 +--------------------+-----------------+ 439 440 SEE ALSO 441 libnvpair(3LIB), attributes(5), nvlist_alloc(9F) 442 443 444 445 February 15, 2016 NVLIST_ALLOC(3NVPAIR)