1nvlist_alloc(3NVPAIR)  Name-value Pair Library Functions nvlist_alloc(3NVPAIR)
2
3
4

NAME

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

SYNOPSIS

12       cc [ flag... ] file... -lnvpair [ library... ]
13       #include <libnvpair.h>
14
15       int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag, int flag);
16
17
18       int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag,
19            nv_alloc_t * nva);
20
21
22       void nvlist_free(nvlist_t *nvl);
23
24
25       int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
26
27
28       int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen,
29            int encoding, int flag);
30
31
32       int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen,
33            int encoding, nv_alloc_t * nva);
34
35
36       int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp,
37            int flag);
38
39
40       int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
41            nv_alloc_t * nva);
42
43
44       int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);
45
46
47       int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp,
48            nv_alloc_t * nva);
49
50
51       int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
52
53
54       nv_alloc_t * nvlist_lookup_nv_alloc(nvlist_t *nvl);
55
56
57       int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
58            /* args */ ...);
59
60
61       void nv_alloc_reset(nv_alloc_t *nva);
62
63
64       void nv_alloc_fini(nv_alloc_t *nva);
65
66

PARAMETERS

68       nvlp        Address of a pointer to nvlist_t.
69
70
71       nvflag      Specify bit fields defining nvlist properties:
72
73                   NV_UNIQUE_NAME         The nvpair names are unique.
74
75
76                   NV_UNIQUE_NAME_TYPE    Name-data   type   combination    is
77                                          unique.
78
79
80
81       flag        Specify 0. Reserved for future use.
82
83
84       nvl         The nvlist_t to be processed.
85
86
87       dst         The destination nvlist_t.
88
89
90       size        Pointer to buffer to contain the encoded size.
91
92
93       bufp        Address  of  buffer  to  pack  nvlist  into. Must be 8-byte
94                   aligned. If NULL, library will allocate memory.
95
96
97       buf         Buffer containing packed nvlist.
98
99
100       buflen      Size of buffer bufp or buf points to.
101
102
103       encoding    Encoding method for packing.
104
105
106       nvo         Pluggable allocator operations pointer (nv_alloc_ops_t).
107
108
109       nva         A pointer to an nv_alloc_t structure to  be  used  for  the
110                   specified nvlist_t.
111
112

DESCRIPTION

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
124
125       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
129
130       The nvlist_free() function frees a name-value pair list.
131
132
133       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
137       NV_ENCODE_NATIVE    Straight bcopy() as described in bcopy(3C).
138
139
140       NV_ENCODE_XDR       Use XDR encoding, suitable for sending  to  another
141                           host.
142
143
144
145       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
149           o      If *bufp is not NULL, *bufp is expected to be a caller-allo‐
150                  cated buffer of size *buflen.
151
152           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
156
157       The nvlist_xpack() function is identical to nvlist_pack()  except  that
158       nvlist_xpack() can use a different allocator.
159
160
161       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
166
167       The nvlist_xunpack() function is identical  to  nvlist_unpack()  except
168       that nvlist_xunpack() can use a different allocator.
169
170
171       The nvlist_dup() function makes a copy of nvl and updates nvlp to point
172       to the copy.
173
174
175       The nvlist_xdup() function is identical  to  nvlist_dup()  except  that
176       nvlist_xdup() can use a different allocator.
177
178
179       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
184
185       The nvlist_lookup_nv_alloc() function  retrieves  the  pointer  to  the
186       allocator that was used when manipulating a name-value pair list.
187
188   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
194
195       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
200
201       The nva argument must be  passed  to  nvlist_xalloc(),  nvlist_xpack(),
202       nvlist_xunpack() and nvlist_xdup().
203
204
205       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
209
210       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
214
215       The  disposition  of the allocated objects and the memory used to store
216       them is left to the allocator implementation.
217
218
219       The nv_alloc_nosleep nv_alloc_t can be  used  with  nvlist_xalloc()  to
220       mimic the behavior of nvlist_alloc().
221
222
223       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
228
229       An example program that uses the pluggable allocator  functionality  is
230       provided on nvlist_alloc(9F).
231
232   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
237         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
243
244
245       The  nva  argument  of the allocator implementation is always the first
246       argument.
247
248
249       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
254
255       The optional (*nv_ao_fini()) function is responsible for the cleanup of
256       the allocator implementation. It is called by nv_alloc_fini().
257
258
259       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
263
264       The optional (*nv_ao_reset()) function is responsible for resetting the
265       nva_arg argument to the data specified by nv_alloc_init().
266
267
268       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
273
274       The disposition of the allocated objects and the memory used  to  store
275       them is left to the allocator implementation.
276

RETURN VALUES

278       These functions return 0 on success and an error value on failure.
279
280
281       The  nvlist_lookup_nv_alloc()  function returns a pointer to an alloca‐
282       tor.
283

ERRORS

285       These functions will fail if:
286
287       EINVAL    There is an invalid argument.
288
289
290
291       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
295       ENOMEM    There is insufficient memory.
296
297
298
299       The nvlist_pack(),  nvlist_unpack(),  nvlist_xpack(),  and  nvlist_xun‐
300       pack() functions will fail if:
301
302       EFAULT     An encode/decode error occurs.
303
304
305       ENOTSUP    An encode/decode method is not supported.
306
307

EXAMPLES

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
317         /* 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
327             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
333             /* 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
342             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
349             /* 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
354             /* free the original list */
355             nvlist_free(nvl);
356             return (err);
357         }
358
359         /* 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
367             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
378         /*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
387             if (create_packed_nvlist(&buf, &buflen, NV_ENCODE_XDR) != 0) {
388                 (void) printf("cannot create packed nvlist buffer\n");
389                 return(-1);
390                 }
391
392             /* 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
399             /* selectively print out attributes */
400             nvlist_lookup_and_print(nvl);
401             return(0);
402         }
403
404

ATTRIBUTES

406       See attributes(5) for descriptions of the following attributes:
407
408
409
410
411       ┌────────────────────────────┬──────────────────────────────┐
412       │      ATTRIBUTE TYPE        │       ATTRIBUTE VALUE        │
413       ├────────────────────────────┼──────────────────────────────┤
414       │Interface Stability         │ Evolving                     │
415       ├────────────────────────────┼──────────────────────────────┤
416       │MT-Level                    │ MT-Safe                      │
417       └────────────────────────────┴──────────────────────────────┘
418

SEE ALSO

420       libnvpair(3LIB), attributes(5), nvlist_alloc(9F)
421
422
423
424SunOS 5.11                        2 Feb 2004             nvlist_alloc(3NVPAIR)
Impressum