1nvlist_alloc(3NVPAIR) Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
2
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
12 cc [ flag... ] file... -lnvpair [ library... ]
13 #include <libnvpair.h>
14 int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag);
16 int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag,
19 nv_alloc_t * nva);
20 void nvlist_free(nvlist_t *nvl);
23 int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
26 int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen,
29 int encoding, int flag);
30 int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen,
33 int encoding, nv_alloc_t * nva);
34 int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp,
37 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,
48 nv_alloc_t * nva);
49 int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
52 nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl);
55 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
58 /* args */ ...);
59 void nv_alloc_reset(nv_alloc_t *nva);
62 void nv_alloc_fini(nv_alloc_t *nva);
65
68 nvlp Address of a pointer to nvlist_t.
69 nvflag Specify bit fields defining nvlist properties:
72 NV_UNIQUE_NAME The nvpair names are unique.
74 NV_UNIQUE_NAME_TYPE Name-data type combination is
77 unique.
78 flag Specify 0. Reserved for future use.
82 nvl The nvlist_t to be processed.
85 dst The destination nvlist_t.
88 size Pointer to buffer to contain the encoded size.
91 bufp Address of buffer to pack nvlist into. Must be 8-byte
94 aligned. If NULL, library will allocate memory.
95 buf Buffer containing packed nvlist.
98 buflen Size of buffer bufp or buf points to.
101 encoding Encoding method for packing.
104 nvo Pluggable allocator operations pointer (nv_alloc_ops_t).
107 nva A pointer to an nv_alloc_t structure to be used for the
110 specified nvlist_t.
111
114 List Manipulation
115 The nvlist_alloc() function allocates a new name-value pair list and
116 updates nvlp to point to the handle. The nvflag argument specifies
117 nvlist properties to remain persistent across packing, unpacking, and
118 duplication. If NV_UNIQUE_NAME was specified for nvflag, existing
119 nvpairs with matching names are removed before the new nvpair is added.
120 If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing nvpairs with
121 matching names and data types are removed before the new nvpair is
122 added. See nvlist_add_byte(3NVPAIR) for more information.
123 The nvlist_xalloc() function is identical to nvlist_alloc() except that
126 nvlist_xalloc() can use a different allocator, as described in the
127 Pluggable Allocators section.
128 The nvlist_free() function frees a name-value pair list.
131 The nvlist_size() function returns the minimum size of a contiguous
134 buffer large enough to pack nvl. The encoding parameter specifies the
135 method of encoding when packing nvl. Supported encoding methods are:
136 NV_ENCODE_NATIVE Straight bcopy() as described in bcopy(3C).
138 NV_ENCODE_XDR Use XDR encoding, suitable for sending to another
141 host.
142 The nvlist_pack() function packs nvl into contiguous memory starting at
146 *bufp. The encoding parameter specifies the method of encoding (see
147 above).
148 o If *bufp is not NULL, *bufp is expected to be a caller-allo‐
150 cated buffer of size *buflen.
151 o If *bufp is NULL, the library will allocate memory and
153 update *bufp to point to the memory and update *buflen to
154 contain the size of the allocated memory.
155 The nvlist_xpack() function is identical to nvlist_pack() except that
158 nvlist_xpack() can use a different allocator.
159 The nvlist_unpack() function takes a buffer with a packed nvlist_t and
162 unpacks it into a searchable nvlist_t. The library allocates memory for
163 nvlist_t. The caller is responsible for freeing the memory by calling
164 nvlist_free().
165 The nvlist_xunpack() function is identical to nvlist_unpack() except
168 that nvlist_xunpack() can use a different allocator.
169 The nvlist_dup() function makes a copy of nvl and updates nvlp to point
172 to the copy.
173 The nvlist_xdup() function is identical to nvlist_dup() except that
176 nvlist_xdup() can use a different allocator.
177 The nvlist_merge() function adds copies of all name-value pairs from
180 nvl to dst. Name-value pairs in dst are replaced with name-value pairs
181 from nvl that have identical names (if dst has the type NV_UNIQUE_NAME)
182 or identical names and types (if dst has the type NV_UNIQUE_NAME_TYPE).
183 The nvlist_lookup_nv_alloc() function retrieves the pointer to the
186 allocator that was used when manipulating a name-value pair list.
187 Pluggable Allocators
189 Using Pluggable Allocators
190 The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions
191 provide an interface to specify the allocator to be used when manipu‐
192 lating a name-value pair list.
193 The nv_alloc_init() function determines the allocator properties and
196 puts them into the nva argument. The application must specify the
197 nv_arg and nvo arguments and an optional variable argument list. The
198 optional arguments are passed to the (*nv_ao_init()) function.
199 The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(),
202 nvlist_xunpack() and nvlist_xdup().
203 The nv_alloc_reset() function is responsible for resetting the alloca‐
206 tor properties to the data specified by nv_alloc_init(). When no
207 (*nv_ao_reset()) function is specified, nv_alloc_reset() has no effect.
208 The nv_alloc_fini() function destroys the allocator properties deter‐
211 mined by nv_alloc_init(). When a (*nv_ao_fini()) function is specified,
212 it is called from nv_alloc_fini().
213 The disposition of the allocated objects and the memory used to store
216 them is left to the allocator implementation.
217 The nv_alloc_nosleep nv_alloc_t can be used with nvlist_xalloc() to
220 mimic the behavior of nvlist_alloc().
221 The nvpair allocator framework provides a pointer to the operation
224 structure of a fixed buffer allocator. This allocator, nv_fixed_ops,
225 uses a pre-allocated buffer for memory allocations. It is intended pri‐
226 marily for kernel use and is described on nvlist_alloc(9F).
227 An example program that uses the pluggable allocator functionality is
230 provided on nvlist_alloc(9F).
231 Creating Pluggable Allocators
233 Any producer of name-value pairs can specify its own allocator func‐
234 tions. The application must provide the following pluggable allocator
235 operations:
236 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
238 void (*nv_ao_fini)(nv_alloc_t *nva);
239 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
240 void (*nv_ao_reset)(nv_alloc_t *nva);
241 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
242 The nva argument of the allocator implementation is always the first
246 argument.
247 The optional (*nv_ao_init()) function is responsible for filling the
250 data specified by nv_alloc_init() into the nva_arg argument. The
251 (*nv_ao_init()) function is only called when nv_alloc_init() is exe‐
252 cuted.
253 The optional (*nv_ao_fini()) function is responsible for the cleanup of
256 the allocator implementation. It is called by nv_alloc_fini().
257 The required (*nv_ao_alloc()) function is used in the nvpair allocation
260 framework for memory allocation. The sz argument specifies the size of
261 the requested buffer.
262 The optional (*nv_ao_reset()) function is responsible for resetting the
265 nva_arg argument to the data specified by nv_alloc_init().
266 The required (*nv_ao_free()) function is used in the nvpair allocator
269 framework for memory deallocation. The buf argument is a pointer to a
270 block previously allocated by the (*nv_ao_alloc()) function. The size
271 argument sz must exactly match the original allocation.
272 The disposition of the allocated objects and the memory used to store
275 them is left to the allocator implementation.
276
278 These functions return 0 on success and an error value on failure.
279 The nvlist_lookup_nv_alloc() function returns a pointer to an alloca‐
282 tor.
283
285 These functions will fail if:
286 EINVAL There is an invalid argument.
288 The nvlist_alloc(), nvlist_dup(), nvlist_pack(), nvlist_unpack(),
292 nvlist_merge(), nvlist_xalloc(), nvlist_xdup(), nvlist_xpack(), and
293 nvlist_xunpack() functions will fail if:
294 ENOMEM There is insufficient memory.
296 The nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and nvlist_xun‐
300 pack() functions will fail if:
301 EFAULT An encode/decode error occurs.
303 ENOTSUP An encode/decode method is not supported.
306
309 /*
310 * Program to create an nvlist.
311 */
312 #include <stdio.h>
313 #include <sys/types.h>
314 #include <string.h>
315 #include <libnvpair.h>
316 /* generate a packed nvlist */
318 static int
319 create_packed_nvlist(char **buf, uint_t *buflen, int encode)
320 {
321 uchar_t bytes[] = {0xaa, 0xbb, 0xcc, 0xdd};
322 int32_t int32[] = {3, 4, 5};
323 char *strs[] = {"child0", "child1", "child2"};
324 int err;
325 nvlist_t *nvl;
326 err = nvlist_alloc(&nvl, NV_UNIQUE_NAME, 0); /* allocate list */
328 if (err) {
329 (void) printf("nvlist_alloc() failed\n");
330 return (err);
331 }
332 /* add a value of some types */
334 if ((nvlist_add_byte(nvl, "byte", bytes[0]) != 0) ||
335 (nvlist_add_int32(nvl, "int32", int32[0]) != 0) ||
336 (nvlist_add_int32_array(nvl, "int32_array", int32, 3) != 0) ||
337 (nvlist_add_string_array(nvl, "string_array", strs, 3) != 0)) {
338 nvlist_free(nvl);
339 return (-1);
340 }
341 err = nvlist_size(nvl, buflen, encode);
343 if (err) {
344 (void) printf("nvlist_size: %s\n", strerror(err));
345 nvlist_free(nvl);
346 return (err);
347 }
348 /* pack into contig. memory */
350 err = nvlist_pack(nvl, buf, buflen, encode, 0);
351 if (err)
352 (void) printf("nvlist_pack: %s\n", strerror(err));
353 /* free the original list */
355 nvlist_free(nvl);
356 return (err);
357 }
358 /* selectively print nvpairs */
360 static void
361 nvlist_lookup_and_print(nvlist_t *nvl)
362 {
363 char **str_val;
364 int i, int_val;
365 uint_t nval;
366 if (nvlist_lookup_int32(nvl, "int32", &int_val) == 0)
368 (void) printf("int32 = %d\n", int_val);
369 if (nvlist_lookup_string_array(nvl, "string_array", &str_val, &nval)
370 == 0) {
371 (void) printf("string_array =");
372 for (i = 0; i < nval; i++)
373 (void) printf(" %s", str_val[i]);
374 (void) printf("\n");
375 }
376 }
377 /*ARGSUSED*/
379 int
380 main(int argc, char *argv[])
381 {
382 int err;
383 char *buf = NULL;
384 size_t buflen;
385 nvlist_t *nvl = NULL;
386 if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
388 (void) printf("cannot create packed nvlist buffer\n");
389 return(-1);
390 }
391 /* unpack into an nvlist_t */
393 err = nvlist_unpack(buf, buflen, &nvl, 0);
394 if (err) {
395 (void) printf("nvlist_unpack(): %s\n", strerror(err));
396 return(-1);
397 }
398 /* selectively print out attributes */
400 nvlist_lookup_and_print(nvl);
401 return(0);
402 }
403
406 See attributes(5) for descriptions of the following attributes:
407 ┌────────────────────────────┬──────────────────────────────┐
412 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
413 ├────────────────────────────┼──────────────────────────────┤
414 │Interface Stability │ Evolving │
415 ├────────────────────────────┼──────────────────────────────┤
416 │MT-Level │ MT-Safe │
417 └────────────────────────────┴──────────────────────────────┘
418
420 libnvpair(3LIB), attributes(5), nvlist_alloc(9F)
421SunOS 5.11 2 Feb 2004 nvlist_alloc(3NVPAIR)