Print this page
patch more-manpage
patch cleanup
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man9f/nvlist_alloc.9f.man.txt
+++ new/usr/src/man/man9f/nvlist_alloc.9f.man.txt
1 1 NVLIST_ALLOC(9F) Kernel Functions for Drivers NVLIST_ALLOC(9F)
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, nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack,
8 8 nvlist_xunpack, nvlist_xdup, nvlist_merge - Manage a name-value pair
9 9 list
10 10
11 11 SYNOPSIS
12 12 #include <sys/nvpair.h>
13 13
14 14 List Manipulation:
15 15
16 16 int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
17 17 int kmflag);
18 18
19 19
20 20 int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);
21 21
22 22
23 23 void nvlist_free(nvlist_t *nvl);
24 24
25 25
26 26 int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
27 27
28 28
29 29 int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
30 30 int flag);
31 31
32 32
33 33 int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
34 34 nv_alloc_t *nva);
35 35
36 36
37 37 int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, 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, nv_alloc_t *nva);
48 48
49 49
50 50 int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
51 51
52 52
53 53 Pluggable Allocator Configuration:
54 54
55 55 nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);
56 56
57 57
58 58 int nv_alloc_init(nv_alloc_t *nva,
59 59 const nv_alloc_ops_t * nvo,/* args */ ...);
60 60
61 61
62 62 void nv_alloc_reset(nv_alloc_t *nva);
63 63
64 64
65 65 void nv_alloc_fini(nv_alloc_t *nva);
66 66
67 67
68 68 Pluggable Allocation Initialization with Fixed Allocator:
69 69
70 70 int nv_alloc_init(nv_alloc_t *nva,
71 71 nv_fixed_ops, void * bufptr, size_t sz);
72 72
73 73
74 74 INTERFACE LEVEL
75 75 Solaris DDI specific (Solaris DDI)
76 76
77 77 PARAMETERS
78 78 nvlp
79 79 Address of a pointer to list of name-value pairs
80 80 (nvlist_t).
81 81
82 82
83 83 nvflag
84 84 Specify bit fields defining nvlist_t properties:
85 85
86 86 NV_UNIQUE_NAME
87 87 nvpair names are unique.
88 88
89 89
90 90 NV_UNIQUE_NAME_TYPE
91 91 Name-data type combination is unique
92 92
93 93
94 94
95 95 kmflag
96 96 Kernel memory allocation policy, either KM_SLEEP or
97 97 KM_NOSLEEP.
98 98
99 99
100 100 nvl
101 101 nvlist_t to be processed.
102 102
103 103
104 104 dst
105 105 Destination nvlist_t.
106 106
107 107
108 108 size
109 109 Pointer to buffer to contain the encoded size.
110 110
111 111
112 112 bufp
113 113 Address of buffer to pack nvlist into. Must be 8-byte
114 114 aligned. If NULL, library will allocate memory.
115 115
116 116
117 117 buf
118 118 Buffer containing packed nvlist_t.
119 119
120 120
121 121 buflen
122 122 Size of buffer bufp or buf points to.
123 123
124 124
125 125 encoding
126 126 Encoding method for packing.
127 127
128 128
129 129 nvo
130 130 Pluggable allocator operations pointer (nv_alloc_ops_t).
131 131
132 132
133 133 nva
134 134 Points to a nv_alloc_t structure to be used for the
135 135 specified nvlist_t.
136 136
137 137
138 138 DESCRIPTION
139 139 List Manipulation:
140 140
141 141
142 142 The nvlist_alloc() function allocates a new name-value pair list and
143 143 updates nvlp to point to the handle. The argument nvflag specifies
144 144 nvlist_t properties to remain persistent across packing, unpacking, and
145 145 duplication.
146 146
147 147
148 148 If NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with
149 149 matching names are removed before the new nvpair is added. If
↓ open down ↓ |
149 lines elided |
↑ open up ↑ |
150 150 NV_UNIQUE_NAME_TYPE is specified for nvflag, existing nvpairs with
151 151 matching names and data types are removed before the new nvpair is
152 152 added. See nvlist_add_byte(9F) for more details.
153 153
154 154
155 155 The nvlist_xalloc() function differs from nvlist_alloc() in that
156 156 nvlist_xalloc() can use a different allocator, as described in the
157 157 Pluggable Allocators section.
158 158
159 159
160 - The nvlist_free() function frees a name-value pair list.
160 + The nvlist_free() function frees a name-value pair list. If nvl is a
161 + null pointer, no action occurs.
161 162
162 163
163 164 The nvlist_size() function returns the minimum size of a contiguous
164 165 buffer large enough to pack nvl. The encoding parameter specifies the
165 166 method of encoding when packing nvl. Supported encoding methods are:
166 167
167 168 NV_ENCODE_NATIVE
168 169 Straight bcopy() as described in bcopy(9F).
169 170
170 171
171 172 NV_ENCODE_XDR
172 173 Use XDR encoding, suitable for sending to another
173 174 host.
174 175
175 176
176 177
177 178 The nvlist_pack() function packs nvl into contiguous memory starting at
178 179 *bufp. The encoding parameter specifies the method of encoding (see
179 180 above).
180 181
181 182 o If *bufp is not NULL, *bufp is expected to be a caller-
182 183 allocated buffer of size *buflen. The kmflag argument is
183 184 ignored.
184 185
185 186 o If *bufp is NULL, the library allocates memory and updates
186 187 *bufp to point to the memory and updates *buflen to contain
187 188 the size of the allocated memory. The value of kmflag
188 189 indicates the memory allocation policy
189 190
190 191
191 192 The nvlist_xpack() function differs from nvlist_pack() in that
192 193 nvlist_xpack() can use a different allocator.
193 194
194 195
195 196 The nvlist_unpack() function takes a buffer with a packed nvlist_t and
196 197 unpacks it into a searchable nvlist_t. The library allocates memory for
197 198 nvlist_t. The caller is responsible for freeing the memory by calling
198 199 nvlist_free().
199 200
200 201
201 202 The nvlist_xunpack() function differs from nvlist_unpack() in that
202 203 nvlist_xunpack() can use a different allocator.
203 204
204 205
205 206 The nvlist_dup() function makes a copy of nvl and updates nvlp to point
206 207 to the copy.
207 208
208 209
209 210 The nvlist_xdup() function differs from nvlist_dup() in that
210 211 nvlist_xdup() can use a different allocator.
211 212
212 213
213 214 The nvlist_merge() function adds copies of all name-value pairs from
214 215 nvlist_t nvl to nvlist_t dst. Name-value pairs in dst are replaced with
215 216 name-value pairs from nvl which have identical names (if dst has the
216 217 type NV_UNIQUE_NAME), or identical names and types (if dst has the type
217 218 NV_UNIQUE_NAME_TYPE).
218 219
219 220
220 221 The nvlist_lookup_nv_alloc() function retrieves the pointer to the
221 222 allocator used when manipulating a name-value pair list.
222 223
223 224 PLUGGABLE ALLOCATORS
224 225 Using Pluggable Allocators:
225 226
226 227
227 228 The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions
228 229 provide an interface that specifies the allocator to be used when
229 230 manipulating a name-value pair list.
230 231
231 232
232 233 The nv_alloc_init() determines allocator properties and puts them into
233 234 the nva argument. You need to specify the nv_arg argument, the nvo
234 235 argument and an optional variable argument list. The optional
235 236 arguments are passed to the (*nv_ao_init()) function.
236 237
237 238
238 239 The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(),
239 240 nvlist_xunpack() and nvlist_xdup().
240 241
241 242
242 243 The nv_alloc_reset() function resets the allocator properties to the
243 244 data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is
244 245 specified, nv_alloc_reset() is without effect.
245 246
246 247
247 248 The nv_alloc_fini() destroys the allocator properties determined by
248 249 nv_alloc_init(). When a (*nv_ao_fini()) routine is specified, it is
249 250 called from nv_alloc_fini().
250 251
251 252
252 253 The disposition of the allocated objects and the memory used to store
253 254 them is left to the allocator implementation.
254 255
255 256
256 257 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be
257 258 used with nvlist_xalloc to mimic the behavior of nvlist_alloc with
258 259 KM_SLEEP and KM_NOSLEEP, respectively.
259 260
260 261 o nv_alloc_nosleep
261 262 o nv_alloc_sleep
262 263
263 264
264 265
265 266 The nvpair framework provides a fixed-buffer allocator, accessible via
266 267 nv_fixed_ops.
267 268
268 269 o nv_fixed_ops
269 270
270 271
271 272
272 273 Given a buffer size and address, the fixed-buffer allocator allows for
273 274 the creation of nvlists in contexts where malloc or kmem_alloc services
274 275 may not be available. The fixed-buffer allocator is designed primarily
275 276 to support the creation of nvlists.
276 277
277 278
278 279 Memory freed using nvlist_free(), pair-removal, or similar routines is
279 280 not reclaimed.
280 281
281 282
282 283 When used to initialize the fixed-buffer allocator, nv_alloc_init
283 284 should be called as follows:
284 285
285 286 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
286 287 void *bufptr, size_t sz);
287 288
288 289
289 290
290 291 When invoked on a fixed-buffer, the nv_alloc_reset() function resets
291 292 the fixed buffer and prepares it for re-use. The framework consumer is
292 293 responsible for freeing the buffer passed to nv_alloc_init().
293 294
294 295 CREATING PLUGGABLE ALLOCATORS
295 296 Any producer of name-value pairs may possibily specify his own
296 297 allocator routines. You must provide the following pluggable allocator
297 298 operations in the allocator implementation.
298 299
299 300 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
300 301 void (*nv_ao_fini)(nv_alloc_t *nva);
301 302 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
302 303 void (*nv_ao_reset)(nv_alloc_t *nva);
303 304 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
304 305
305 306
306 307
307 308 The nva argument of the allocator implementation is always the first
308 309 argument.
309 310
310 311
311 312 The optional (*nv_ao_init() ) function is responsible for filling the
312 313 data specified by nv_alloc_init() into the nva_arg() argument. The
313 314 (*nv_ao_init()) function is called only when nv_alloc_init() is
314 315 executed.
315 316
316 317
317 318 The optional (*nv_ao_fini()) function is responsible for the cleanup of
318 319 the allocator implementation. It is called by nv_alloc_fini().
319 320
320 321
321 322 The required (*nv_ao_alloc()) function is used in the nvpair allocation
322 323 framework for memory allocation. The sz argument specifies the size of
323 324 the requested buffer.
324 325
325 326
326 327 The optional (*nv_ao_reset()) function is responsible for resetting the
327 328 nva_arg argument to the data specified by nv_alloc_init().
328 329
329 330
330 331 The required (*nv_ao_free()) function is used in the nvpair allocator
331 332 framework for memory de-allocation. The argument buf is a pointer to a
332 333 block previously allocated by (*nv_ao_alloc()) function. The size
333 334 argument sz must exactly match the original allocation.
334 335
335 336
336 337 The disposition of the allocated objects and the memory used to store
337 338 them is left to the allocator implementation.
338 339
339 340 RETURN VALUES
340 341 For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():
341 342
342 343 0
343 344 success
344 345
345 346
346 347 EINVAL
347 348 invalid argument
348 349
349 350
350 351 ENOMEM
351 352 insufficient memory
352 353
353 354
354 355
355 356 For nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and
356 357 nvlist_xunpack():
357 358
358 359 0
359 360 success
360 361
361 362
362 363 EINVAL
363 364 invalid argument
364 365
365 366
366 367 ENOMEM
367 368 insufficient memory
368 369
369 370
370 371 EFAULT
371 372 encode/decode error
372 373
373 374
374 375 ENOTSUP
375 376 encode/decode method not supported
376 377
377 378
378 379
379 380 For nvlist_size():
380 381
381 382 0
382 383 success
383 384
384 385
385 386 EINVAL
386 387 invalid argument
387 388
388 389
389 390
390 391 For nvlist_lookup_nv_alloc():
391 392
392 393
393 394 pointer to the allocator
394 395
395 396 USAGE
396 397 The fixed-buffer allocator is very simple allocator. It uses a pre-
397 398 allocated buffer for memory allocations and it can be used in interrupt
398 399 context. You are responsible for allocation and de-allocation for the
399 400 pre-allocated buffer.
400 401
401 402 EXAMPLES
402 403 /*
403 404 * using the fixed-buffer allocator.
404 405 */
405 406 #include <sys/nvpair.h>
406 407
407 408 /* initialize the nvpair allocator framework */
408 409 static nv_alloc_t *
409 410 init(char *buf, size_t size)
410 411 {
411 412 nv_alloc_t *nvap;
412 413
413 414 if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
414 415 return (NULL);
415 416
416 417 if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
417 418 return (nvap);
418 419
419 420 return (NULL);
420 421 }
421 422
422 423 static void
423 424 fini(nv_alloc_t *nvap)
424 425 {
425 426 nv_alloc_fini(nvap);
426 427 kmem_free(nvap, sizeof(nv_alloc_t));
427 428 }
428 429 static int
429 430 interrupt_context(nv_alloc_t *nva)
430 431 {
431 432 nvlist_t *nvl;
432 433 int error;
433 434
434 435 if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
435 436 return (-1);
436 437
437 438 if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
438 439 error = send_nvl(nvl);
439 440
440 441 nvlist_free(nvl);
441 442 return (error);
442 443 }
443 444
444 445
445 446 CONTEXT
446 447 The nvlist_alloc(), nvlist_pack(), nvlist_unpack(), and nvlist_dup()
447 448 functions can be called from interrupt context only if the KM_NOSLEEP
448 449 flag is set. They can be called from user context with any valid flag.
449 450
450 451
451 452 The nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack(), and
452 453 nvlist_xdup() functions can be called from interrupt context only if
↓ open down ↓ |
282 lines elided |
↑ open up ↑ |
453 454 (1) the default allocator is used and the KM_NOSLEEP flag is set or (2)
454 455 the specified allocator did not sleep for free memory (for example, it
455 456 uses a pre-allocated buffer for memory allocations).
456 457
457 458
458 459 These functions can be called from user or kernel context with any
459 460 valid flag.
460 461
461 462
462 463
463 - January 16, 2006 NVLIST_ALLOC(9F)
464 + February 15, 2016 NVLIST_ALLOC(9F)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX