1 '\" te
2 .\" Copyright (c) 2006, 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 9F "Jan 16, 2006"
7 .SH NAME
8 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup,
9 nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack, nvlist_xunpack,
10 nvlist_xdup, nvlist_merge \- Manage a name-value pair list
11 .SH SYNOPSIS
12 .LP
13 .nf
14 #include <sys/nvpair.h>
15
16 List Manipulation:
17
18 \fBint\fR \fBnvlist_alloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR,
19 \fBint\fR \fIkmflag\fR);
20 .fi
21
22 .LP
23 .nf
24 \fBint\fR \fBnvlist_xalloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, \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, \fBint\fR \fIencoding\fR,
40 \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, \fBint\fR \fIencoding\fR,
46 \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, \fBint\fR \fIflag\fR);
52 .fi
53
54 .LP
55 .nf
56 \fBint\fR \fBnvlist_xunpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR,
57 \fBnv_alloc_t *\fR\fInva\fR);
58 .fi
59
60 .LP
61 .nf
62 \fBint\fR \fBnvlist_dup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR);
63 .fi
64
65 .LP
66 .nf
67 \fBint\fR \fBnvlist_xdup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBnv_alloc_t *\fR\fInva\fR);
68 .fi
69
70 .LP
71 .nf
72 \fBint\fR \fBnvlist_merge\fR(\fBnvlist_t *\fR\fIdst\fR, \fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag\fR);
73 .fi
74
75 .LP
76 .nf
77 Pluggable Allocator Configuration:
78
79 \fBnv_alloc_t *\fR\fBnvlist_lookup_nv_alloc\fR(\fBnvlist_t *);\fR
80 .fi
81
82 .LP
83 .nf
84 \fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR,
85 \fBconst nv_alloc_ops_t *\fR \fInvo,\fR/* args */ ...);
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 .LP
99 .nf
100 Pluggable Allocation Initialization with Fixed Allocator:
101
102 \fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR,
103 \fBnv_fixed_ops\fR, \fBvoid *\fR \fIbufptr\fR, \fBsize_t\fR sz);
104 .fi
105
106 .SH INTERFACE LEVEL
107 .sp
108 .LP
109 Solaris DDI specific (Solaris DDI)
110 .SH PARAMETERS
111 .sp
112 .ne 2
113 .na
114 \fB\fInvlp\fR\fR
115 .ad
116 .RS 12n
117 Address of a pointer to list of name-value pairs (\fBnvlist_t\fR).
118 .RE
119
120 .sp
121 .ne 2
122 .na
123 \fB\fInvflag\fR\fR
124 .ad
125 .RS 12n
126 Specify bit fields defining \fBnvlist_t\fR properties:
127 .sp
128 .ne 2
129 .na
130 \fB\fBNV_UNIQUE_NAME\fR\fR
131 .ad
132 .RS 23n
133 \fBnvpair\fR names are unique.
134 .RE
135
136 .sp
137 .ne 2
138 .na
139 \fB\fBNV_UNIQUE_NAME_TYPE\fR\fR
140 .ad
141 .RS 23n
142 Name-data type combination is unique
143 .RE
144
145 .RE
146
147 .sp
148 .ne 2
149 .na
150 \fB\fIkmflag\fR\fR
151 .ad
152 .RS 12n
153 Kernel memory allocation policy, either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR.
154 .RE
155
156 .sp
157 .ne 2
158 .na
159 \fB\fInvl\fR\fR
160 .ad
161 .RS 12n
162 \fBnvlist_t\fR to be processed.
163 .RE
164
165 .sp
166 .ne 2
167 .na
168 \fB\fIdst\fR\fR
169 .ad
170 .RS 12n
171 Destination \fBnvlist_t\fR.
172 .RE
173
174 .sp
175 .ne 2
176 .na
177 \fB\fIsize\fR\fR
178 .ad
179 .RS 12n
180 Pointer to buffer to contain the encoded size.
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fB\fIbufp\fR\fR
187 .ad
188 .RS 12n
189 Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If NULL,
190 library will allocate memory.
191 .RE
192
193 .sp
194 .ne 2
195 .na
196 \fB\fIbuf\fR\fR
197 .ad
198 .RS 12n
199 Buffer containing packed \fBnvlist_t\fR.
200 .RE
201
202 .sp
203 .ne 2
204 .na
205 \fB\fIbuflen\fR\fR
206 .ad
207 .RS 12n
208 Size of buffer \fIbufp\fR or \fIbuf\fR points to.
209 .RE
210
211 .sp
212 .ne 2
213 .na
214 \fB\fIencoding\fR\fR
215 .ad
216 .RS 12n
217 Encoding method for packing.
218 .RE
219
220 .sp
221 .ne 2
222 .na
223 \fB\fInvo\fR\fR
224 .ad
225 .RS 12n
226 Pluggable allocator operations pointer (nv_alloc_ops_t).
227 .RE
228
229 .sp
230 .ne 2
231 .na
232 \fB\fInva\fR\fR
233 .ad
234 .RS 12n
235 Points to a nv_alloc_t structure to be used for the specified \fBnvlist_t\fR.
236 .RE
237
238 .SH DESCRIPTION
239 .sp
240 .LP
241 List Manipulation:
242 .sp
243 .LP
244 The \fBnvlist_alloc()\fR function allocates a new name-value pair list and
245 updates \fInvlp\fR to point to the handle. The argument \fInvflag\fR specifies
246 \fBnvlist_t\fR properties to remain persistent across packing, unpacking, and
247 duplication.
248 .sp
249 .LP
250 If \fBNV_UNIQUE_NAME\fR is specified for nvflag, existing nvpairs with matching
251 names are removed before the new nvpair is added. If \fBNV_UNIQUE_NAME_TYPE\fR
252 is specified for nvflag, existing nvpairs with matching names and data types
253 are removed before the new nvpair is added. See \fBnvlist_add_byte\fR(9F) for
254 more details.
255 .sp
256 .LP
257 The \fBnvlist_xalloc()\fR function differs from \fBnvlist_alloc()\fR in that
258 \fBnvlist_xalloc()\fR can use a different allocator, as described in the
259 Pluggable Allocators section.
260 .sp
261 .LP
262 The \fBnvlist_free()\fR function frees a name-value pair list.
263 .sp
264 .LP
265 The \fBnvlist_size()\fR function returns the minimum size of a contiguous
266 buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies
267 the method of encoding when packing \fInvl\fR. Supported encoding methods are:
268 .sp
269 .ne 2
270 .na
271 \fB\fBNV_ENCODE_NATIVE\fR\fR
272 .ad
273 .RS 20n
274 Straight \fBbcopy()\fR as described in \fBbcopy\fR(9F).
275 .RE
276
277 .sp
278 .ne 2
279 .na
280 \fB\fBNV_ENCODE_XDR\fR\fR
281 .ad
282 .RS 20n
283 Use XDR encoding, suitable for sending to another host.
284 .RE
285
286 .sp
287 .LP
288 The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory
289 starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of
290 encoding (see above).
291 .RS +4
292 .TP
293 .ie t \(bu
294 .el o
295 If *\fIbufp\fR is not NULL, *\fIbufp\fR is expected to be a caller-allocated
296 buffer of size *\fIbuflen\fR. The \fIkmflag\fR argument is ignored.
297 .RE
298 .RS +4
299 .TP
300 .ie t \(bu
301 .el o
302 If *\fIbufp\fR is NULL, the library allocates memory and updates *\fIbufp\fR to
303 point to the memory and updates *\fIbuflen\fR to contain the size of the
304 allocated memory. The value of \fIkmflag\fR indicates the memory allocation
305 policy
306 .RE
307 .sp
308 .LP
309 The \fBnvlist_xpack()\fR function differs from \fBnvlist_pack()\fR in that
310 \fBnvlist_xpack()\fR can use a different allocator.
311 .sp
312 .LP
313 The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR
314 and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory
315 for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling
316 \fBnvlist_free()\fR.
317 .sp
318 .LP
319 The \fBnvlist_xunpack()\fR function differs from \fBnvlist_unpack()\fR in that
320 \fBnvlist_xunpack()\fR can use a different allocator.
321 .sp
322 .LP
323 The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates
324 \fInvlp\fR to point to the copy.
325 .sp
326 .LP
327 The \fBnvlist_xdup()\fR function differs from \fBnvlist_dup()\fR in that
328 \fBnvlist_xdup()\fR can use a different allocator.
329 .sp
330 .LP
331 The \fBnvlist_merge()\fR function adds copies of all name-value pairs from
332 \fBnvlist_t\fR \fInvl\fR to \fBnvlist_t dst\fR. Name-value pairs in dst are
333 replaced with name-value pairs from \fBnvl\fR which have identical names (if
334 dst has the type \fBNV_UNIQUE_NAME\fR), or identical names and types (if dst
335 has the type \fBNV_UNIQUE_NAME_TYPE\fR).
336 .sp
337 .LP
338 The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the
339 allocator used when manipulating a name-value pair list.
340 .SS "PLUGGABLE ALLOCATORS"
341 .sp
342 .LP
343 Using Pluggable Allocators:
344 .sp
345 .LP
346 The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR
347 functions provide an interface that specifies the allocator to be used when
348 manipulating a name-value pair list.
349 .sp
350 .LP
351 The \fBnv_alloc_init()\fR determines allocator properties and puts them into
352 the \fInva\fR argument. You need to specify the \fInv_arg\fR argument, the
353 \fInvo\fR argument and an optional variable argument list. The optional
354 arguments are passed to the (*\fBnv_ao_init()\fR) function.
355 .sp
356 .LP
357 The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR,
358 \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR.
359 .sp
360 .LP
361 The \fBnv_alloc_reset()\fR function resets the allocator properties to the data
362 specified by \fBnv_alloc_init()\fR. When no (*\fBnv_ao_reset()\fR) function is
363 specified, \fBnv_alloc_reset()\fR is without effect.
364 .sp
365 .LP
366 The \fBnv_alloc_fini()\fR destroys the allocator properties determined by
367 \fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) routine is specified, it is
368 called from \fBnv_alloc_fini()\fR.
369 .sp
370 .LP
371 The disposition of the allocated objects and the memory used to store them is
372 left to the allocator implementation.
373 .sp
374 .LP
375 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used
376 with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and
377 KM_NOSLEEP, respectively.
378 .sp
379 .in +2
380 .nf
381 o nv_alloc_nosleep
382 o nv_alloc_sleep
383 .fi
384 .in -2
385
386 .sp
387 .LP
388 The nvpair framework provides a fixed-buffer allocator, accessible via
389 nv_fixed_ops.
390 .sp
391 .in +2
392 .nf
393 o nv_fixed_ops
394 .fi
395 .in -2
396
397 .sp
398 .LP
399 Given a buffer size and address, the fixed-buffer allocator allows for the
400 creation of nvlists in contexts where malloc or kmem_alloc services may not be
401 available. The fixed-buffer allocator is designed primarily to support the
402 creation of nvlists.
403 .sp
404 .LP
405 Memory freed using \fBnvlist_free()\fR, pair-removal, or similar routines is
406 not reclaimed.
407 .sp
408 .LP
409 When used to initialize the fixed-buffer allocator, nv_alloc_init should be
410 called as follows:
411 .sp
412 .in +2
413 .nf
414 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
415 void *bufptr, size_t sz);
416 .fi
417 .in -2
418
419 .sp
420 .LP
421 When invoked on a fixed-buffer, the \fBnv_alloc_reset()\fR function resets the
422 fixed buffer and prepares it for re-use. The framework consumer is responsible
423 for freeing the buffer passed to \fBnv_alloc_init()\fR.
424 .SS "CREATING PLUGGABLE ALLOCATORS"
425 .sp
426 .LP
427 Any producer of name-value pairs may possibily specify his own allocator
428 routines. You must provide the following pluggable allocator operations in the
429 allocator implementation.
430 .sp
431 .in +2
432 .nf
433 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
434 void (*nv_ao_fini)(nv_alloc_t *nva);
435 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
436 void (*nv_ao_reset)(nv_alloc_t *nva);
437 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
438 .fi
439 .in -2
440
441 .sp
442 .LP
443 The \fInva\fR argument of the allocator implementation is always the first
444 argument.
445 .sp
446 .LP
447 The optional (*\fBnv_ao_init()\fR ) function is responsible for filling the
448 data specified by \fBnv_alloc_init()\fR into the \fBnva_arg()\fR argument. The
449 (*\fBnv_ao_init()\fR) function is called only when \fBnv_alloc_init()\fR is
450 executed.
451 .sp
452 .LP
453 The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of
454 the allocator implementation. It is called by \fBnv_alloc_fini()\fR.
455 .sp
456 .LP
457 The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation
458 framework for memory allocation. The sz argument specifies the size of the
459 requested buffer.
460 .sp
461 .LP
462 The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the
463 nva_arg argument to the data specified by \fBnv_alloc_init()\fR.
464 .sp
465 .LP
466 The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator
467 framework for memory de-allocation. The argument buf is a pointer to a block
468 previously allocated by (*\fBnv_ao_alloc()\fR) function. The size argument sz
469 must exactly match the original allocation.
470 .sp
471 .LP
472 The disposition of the allocated objects and the memory used to store them is
473 left to the allocator implementation.
474 .SH RETURN VALUES
475 .sp
476 .LP
477 For \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_xalloc()\fR, and
478 \fBnvlist_xdup()\fR:
479 .sp
480 .ne 2
481 .na
482 \fB\fB0\fR\fR
483 .ad
484 .RS 10n
485 success
486 .RE
487
488 .sp
489 .ne 2
490 .na
491 \fB\fBEINVAL\fR\fR
492 .ad
493 .RS 10n
494 invalid argument
495 .RE
496
497 .sp
498 .ne 2
499 .na
500 \fB\fBENOMEM\fR\fR
501 .ad
502 .RS 10n
503 insufficient memory
504 .RE
505
506 .sp
507 .LP
508 For \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and
509 \fBnvlist_xunpack()\fR:
510 .sp
511 .ne 2
512 .na
513 \fB\fB0\fR\fR
514 .ad
515 .RS 11n
516 success
517 .RE
518
519 .sp
520 .ne 2
521 .na
522 \fB\fBEINVAL\fR\fR
523 .ad
524 .RS 11n
525 invalid argument
526 .RE
527
528 .sp
529 .ne 2
530 .na
531 \fB\fBENOMEM\fR\fR
532 .ad
533 .RS 11n
534 insufficient memory
535 .RE
536
537 .sp
538 .ne 2
539 .na
540 \fB\fBEFAULT\fR\fR
541 .ad
542 .RS 11n
543 encode/decode error
544 .RE
545
546 .sp
547 .ne 2
548 .na
549 \fB\fBENOTSUP\fR\fR
550 .ad
551 .RS 11n
552 encode/decode method not supported
553 .RE
554
555 .sp
556 .LP
557 For \fBnvlist_size()\fR:
558 .sp
559 .ne 2
560 .na
561 \fB\fB0\fR\fR
562 .ad
563 .RS 10n
564 success
565 .RE
566
567 .sp
568 .ne 2
569 .na
570 \fB\fBEINVAL\fR\fR
571 .ad
572 .RS 10n
573 invalid argument
574 .RE
575
576 .sp
577 .LP
578 For \fBnvlist_lookup_nv_alloc()\fR:
579 .sp
580 .LP
581 pointer to the allocator
582 .SH USAGE
583 .sp
584 .LP
585 The fixed-buffer allocator is very simple allocator. It uses a pre-allocated
586 buffer for memory allocations and it can be used in interrupt context. You are
587 responsible for allocation and de-allocation for the pre-allocated buffer.
588 .SH EXAMPLES
589 .sp
590 .in +2
591 .nf
592 /*
593 * using the fixed-buffer allocator.
594 */
595 #include <sys/nvpair.h>
596
597 /* initialize the nvpair allocator framework */
598 static nv_alloc_t *
599 init(char *buf, size_t size)
600 {
601 nv_alloc_t *nvap;
602
603 if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
604 return (NULL);
605
606 if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
607 return (nvap);
608
609 return (NULL);
610 }
611
612 static void
613 fini(nv_alloc_t *nvap)
614 {
615 nv_alloc_fini(nvap);
616 kmem_free(nvap, sizeof(nv_alloc_t));
617 }
618 static int
619 interrupt_context(nv_alloc_t *nva)
620 {
621 nvlist_t *nvl;
622 int error;
623
624 if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
625 return (-1);
626
627 if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
628 error = send_nvl(nvl);
629
630 nvlist_free(nvl);
631 return (error);
632 }
633 .fi
634 .in -2
635
636 .SH CONTEXT
637 .sp
638 .LP
639 The \fBnvlist_alloc()\fR, \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, and
640 \fBnvlist_dup()\fR functions can be called from interrupt context only if the
641 \fBKM_NOSLEEP\fR flag is set. They can be called from user context with any
642 valid flag.
643 .sp
644 .LP
645 The \fBnvlist_xalloc()\fR, \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR, and
646 \fBnvlist_xdup()\fR functions can be called from interrupt context only if (1)
647 the default allocator is used and the \fBKM_NOSLEEP\fR flag is set or (2) the
648 specified allocator did not sleep for free memory (for example, it uses a
649 pre-allocated buffer for memory allocations).
650 .sp
651 .LP
652 These functions can be called from user or kernel context with any valid flag.