1nvlist_alloc(9F) Kernel Functions for Drivers nvlist_alloc(9F)
2
6 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack,
7 nvlist_dup, nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack,
8 nvlist_xunpack, nvlist_xdup, nvlist_merge - Manage a name-value pair
9 list
10
12 #include <sys/nvpair.h>
13 List Manipulation:
15 int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
17 int kmflag);
18 int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);
21 void nvlist_free(nvlist_t *nvl);
24 int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
27 int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
30 int flag);
31 int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
34 nv_alloc_t *nva);
35 int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, int flag);
38 int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
41 nv_alloc_t *nva);
42 int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);
45 int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp, nv_alloc_t *nva);
48 int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
51 Pluggable Allocator Configuration:
54 nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);
56 int nv_alloc_init(nv_alloc_t *nva,
59 const nv_alloc_ops_t * nvo,/* args */ ...);
60 void nv_alloc_reset(nv_alloc_t *nva);
63 void nv_alloc_fini(nv_alloc_t *nva);
66 Pluggable Allocation Initialization with Fixed Allocator:
69 int nv_alloc_init(nv_alloc_t *nva,
71 nv_fixed_ops, void * bufptr, size_t sz);
72
75 Solaris DDI specific (Solaris DDI)
76
78 nvlp Address of a pointer to list of name-value pairs
79 (nvlist_t).
80 nvflag Specify bit fields defining nvlist_t properties:
83 NV_UNIQUE_NAME nvpair names are unique.
85 NV_UNIQUE_NAME_TYPE Name-data type combination is unique
88 kmflag Kernel memory allocation policy, either KM_SLEEP or
92 KM_NOSLEEP.
93 nvl nvlist_t to be processed.
96 dst Destination nvlist_t.
99 size Pointer to buffer to contain the encoded size.
102 bufp Address of buffer to pack nvlist into. Must be 8-byte
105 aligned. If NULL, library will allocate memory.
106 buf Buffer containing packed nvlist_t.
109 buflen Size of buffer bufp or buf points to.
112 encoding Encoding method for packing.
115 nvo Pluggable allocator operations pointer (nv_alloc_ops_t).
118 nva Points to a nv_alloc_t structure to be used for the speci‐
121 fied nvlist_t.
122
125 List Manipulation:
126 The nvlist_alloc() function allocates a new name-value pair list and
129 updates nvlp to point to the handle. The argument nvflag specifies
130 nvlist_t properties to remain persistent across packing, unpacking, and
131 duplication.
132 If NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with match‐
135 ing names are removed before the new nvpair is added. If
136 NV_UNIQUE_NAME_TYPE is specified for nvflag, existing nvpairs with
137 matching names and data types are removed before the new nvpair is
138 added. See nvlist_add_byte(9F) for more details.
139 The nvlist_xalloc() function differs from nvlist_alloc() in that
142 nvlist_xalloc() can use a different allocator, as described in the
143 Pluggable Allocators section.
144 The nvlist_free() function frees a name-value pair list.
147 The nvlist_size() function returns the minimum size of a contiguous
150 buffer large enough to pack nvl. The encoding parameter specifies the
151 method of encoding when packing nvl. Supported encoding methods are:
152 NV_ENCODE_NATIVE Straight bcopy() as described in bcopy(9F).
154 NV_ENCODE_XDR Use XDR encoding, suitable for sending to another
157 host.
158 The nvlist_pack() function packs nvl into contiguous memory starting at
162 *bufp. The encoding parameter specifies the method of encoding (see
163 above).
164 o If *bufp is not NULL, *bufp is expected to be a caller-allo‐
166 cated buffer of size *buflen. The kmflag argument is
167 ignored.
168 o If *bufp is NULL, the library allocates memory and updates
170 *bufp to point to the memory and updates *buflen to contain
171 the size of the allocated memory. The value of kmflag indi‐
172 cates the memory allocation policy
173 The nvlist_xpack() function differs from nvlist_pack() in that
176 nvlist_xpack() can use a different allocator.
177 The nvlist_unpack() function takes a buffer with a packed nvlist_t and
180 unpacks it into a searchable nvlist_t. The library allocates memory for
181 nvlist_t. The caller is responsible for freeing the memory by calling
182 nvlist_free().
183 The nvlist_xunpack() function differs from nvlist_unpack() in that
186 nvlist_xunpack() can use a different allocator.
187 The nvlist_dup() function makes a copy of nvl and updates nvlp to point
190 to the copy.
191 The nvlist_xdup() function differs from nvlist_dup() in that
194 nvlist_xdup() can use a different allocator.
195 The nvlist_merge() function adds copies of all name-value pairs from
198 nvlist_t nvl to nvlist_t dst. Name-value pairs in dst are replaced with
199 name-value pairs from nvl which have identical names (if dst has the
200 type NV_UNIQUE_NAME), or identical names and types (if dst has the type
201 NV_UNIQUE_NAME_TYPE).
202 The nvlist_lookup_nv_alloc() function retrieves the pointer to the
205 allocator used when manipulating a name-value pair list.
206 PLUGGABLE ALLOCATORS
208 Using Pluggable Allocators:
209 The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions
212 provide an interface that specifies the allocator to be used when
213 manipulating a name-value pair list.
214 The nv_alloc_init() determines allocator properties and puts them into
217 the nva argument. You need to specify the nv_arg argument, the nvo
218 argument and an optional variable argument list. The optional argu‐
219 ments are passed to the (*nv_ao_init()) function.
220 The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(),
223 nvlist_xunpack() and nvlist_xdup().
224 The nv_alloc_reset() function resets the allocator properties to the
227 data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is
228 specified, nv_alloc_reset() is without effect.
229 The nv_alloc_fini() destroys the allocator properties determined by
232 nv_alloc_init(). When a (*nv_ao_fini()) routine is specified, it is
233 called from nv_alloc_fini().
234 The disposition of the allocated objects and the memory used to store
237 them is left to the allocator implementation.
238 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be
241 used with nvlist_xalloc to mimic the behavior of nvlist_alloc with
242 KM_SLEEP and KM_NOSLEEP, respectively.
243 o nv_alloc_nosleep
245 o nv_alloc_sleep
246 The nvpair framework provides a fixed-buffer allocator, accessible via
250 nv_fixed_ops.
251 o nv_fixed_ops
253 Given a buffer size and address, the fixed-buffer allocator allows for
257 the creation of nvlists in contexts where malloc or kmem_alloc services
258 may not be available. The fixed-buffer allocator is designed primarily
259 to support the creation of nvlists.
260 Memory freed using nvlist_free(), pair-removal, or similar routines is
263 not reclaimed.
264 When used to initialize the fixed-buffer allocator, nv_alloc_init
267 should be called as follows:
268 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
270 void *bufptr, size_t sz);
271 When invoked on a fixed-buffer, the nv_alloc_reset() function resets
275 the fixed buffer and prepares it for re-use. The framework consumer is
276 responsible for freeing the buffer passed to nv_alloc_init().
277 CREATING PLUGGABLE ALLOCATORS
279 Any producer of name-value pairs may possibily specify his own alloca‐
280 tor routines. You must provide the following pluggable allocator opera‐
281 tions in the allocator implementation.
282 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
284 void (*nv_ao_fini)(nv_alloc_t *nva);
285 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
286 void (*nv_ao_reset)(nv_alloc_t *nva);
287 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
288 The nva argument of the allocator implementation is always the first
292 argument.
293 The optional (*nv_ao_init() ) function is responsible for filling the
296 data specified by nv_alloc_init() into the nva_arg() argument. The
297 (*nv_ao_init()) function is called only when nv_alloc_init() is exe‐
298 cuted.
299 The optional (*nv_ao_fini()) function is responsible for the cleanup of
302 the allocator implementation. It is called by nv_alloc_fini().
303 The required (*nv_ao_alloc()) function is used in the nvpair allocation
306 framework for memory allocation. The sz argument specifies the size of
307 the requested buffer.
308 The optional (*nv_ao_reset()) function is responsible for resetting the
311 nva_arg argument to the data specified by nv_alloc_init().
312 The required (*nv_ao_free()) function is used in the nvpair allocator
315 framework for memory de-allocation. The argument buf is a pointer to a
316 block previously allocated by (*nv_ao_alloc()) function. The size argu‐
317 ment sz must exactly match the original allocation.
318 The disposition of the allocated objects and the memory used to store
321 them is left to the allocator implementation.
322
324 For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():
325 0 success
327 EINVAL invalid argument
330 ENOMEM insufficient memory
333 For nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and nvlist_xun‐
337 pack():
338 0 success
340 EINVAL invalid argument
343 ENOMEM insufficient memory
346 EFAULT encode/decode error
349 ENOTSUP encode/decode method not supported
352 For nvlist_size():
356 0 success
358 EINVAL invalid argument
361 For nvlist_lookup_nv_alloc():
365 pointer to the allocator
368
370 The fixed-buffer allocator is very simple allocator. It uses a pre-
371 allocated buffer for memory allocations and it can be used in interrupt
372 context. You are responsible for allocation and de-allocation for the
373 pre-allocated buffer.
374
376 /*
377 * using the fixed-buffer allocator.
378 */
379 #include <sys/nvpair.h>
380 /* initialize the nvpair allocator framework */
382 static nv_alloc_t *
383 init(char *buf, size_t size)
384 {
385 nv_alloc_t *nvap;
386 if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
388 return (NULL);
389 if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
391 return (nvap);
392 return (NULL);
394 }
395 static void
397 fini(nv_alloc_t *nvap)
398 {
399 nv_alloc_fini(nvap);
400 kmem_free(nvap, sizeof(nv_alloc_t));
401 }
402 static int
403 interrupt_context(nv_alloc_t *nva)
404 {
405 nvlist_t *nvl;
406 int error;
407 if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
409 return (-1);
410 if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
412 error = send_nvl(nvl);
413 nvlist_free(nvl);
415 return (error);
416 }
417
420 The nvlist_alloc(), nvlist_pack(), nvlist_unpack(), and nvlist_dup()
421 functions can be called from interrupt context only if the KM_NOSLEEP
422 flag is set. They can be called from user context with any valid flag.
423 The nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack(), and
426 nvlist_xdup() functions can be called from interrupt context only if
427 (1) the default allocator is used and the KM_NOSLEEP flag is set or (2)
428 the specified allocator did not sleep for free memory (for example, it
429 uses a pre-allocated buffer for memory allocations).
430 These functions can be called from user or kernel context with any
433 valid flag.
434SunOS 5.11 16 Jan 2006 nvlist_alloc(9F)