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