1nvlist_alloc(9F)         Kernel Functions for Drivers         nvlist_alloc(9F)
2
3
4

NAME

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

SYNOPSIS

12       #include <sys/nvpair.h>
13
14       List Manipulation:
15
16       int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
17            int kmflag);
18
19
20       int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);
21
22
23       void nvlist_free(nvlist_t *nvl);
24
25
26       int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
27
28
29       int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
30            int flag);
31
32
33       int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
34            nv_alloc_t *nva);
35
36
37       int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, 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, nv_alloc_t *nva);
48
49
50       int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
51
52
53       Pluggable Allocator Configuration:
54
55       nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);
56
57
58       int nv_alloc_init(nv_alloc_t *nva,
59            const nv_alloc_ops_t * nvo,/* args */ ...);
60
61
62       void  nv_alloc_reset(nv_alloc_t  *nva);
63
64
65       void  nv_alloc_fini(nv_alloc_t *nva);
66
67
68       Pluggable Allocation Initialization with Fixed Allocator:
69
70       int nv_alloc_init(nv_alloc_t *nva,
71            nv_fixed_ops, void * bufptr,  size_t sz);
72
73

INTERFACE LEVEL

75       Solaris DDI specific (Solaris DDI)
76

PARAMETERS

78       nvlp        Address  of  a  pointer  to  list   of   name-value   pairs
79                   (nvlist_t).
80
81
82       nvflag      Specify bit fields defining nvlist_t properties:
83
84                   NV_UNIQUE_NAME         nvpair names are unique.
85
86
87                   NV_UNIQUE_NAME_TYPE    Name-data type combination is unique
88
89
90
91       kmflag      Kernel   memory   allocation  policy,  either  KM_SLEEP  or
92                   KM_NOSLEEP.
93
94
95       nvl         nvlist_t to be processed.
96
97
98       dst         Destination nvlist_t.
99
100
101       size        Pointer to buffer to contain the encoded size.
102
103
104       bufp        Address of buffer to  pack  nvlist  into.  Must  be  8-byte
105                   aligned. If NULL, library will allocate memory.
106
107
108       buf         Buffer containing packed nvlist_t.
109
110
111       buflen      Size of buffer bufp or buf points to.
112
113
114       encoding    Encoding method for packing.
115
116
117       nvo         Pluggable allocator operations pointer (nv_alloc_ops_t).
118
119
120       nva         Points  to a nv_alloc_t structure to be used for the speci‐
121                   fied nvlist_t.
122
123

DESCRIPTION

125       List Manipulation:
126
127
128       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
133
134       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
140
141       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
145
146       The nvlist_free() function frees a name-value pair list.
147
148
149       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
153       NV_ENCODE_NATIVE    Straight bcopy() as described in bcopy(9F).
154
155
156       NV_ENCODE_XDR       Use  XDR  encoding, suitable for sending to another
157                           host.
158
159
160
161       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
165           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
169           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
174
175       The   nvlist_xpack()   function  differs  from  nvlist_pack()  in  that
176       nvlist_xpack() can use a different allocator.
177
178
179       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
184
185       The  nvlist_xunpack()  function  differs  from  nvlist_unpack() in that
186       nvlist_xunpack() can use a different allocator.
187
188
189       The nvlist_dup() function makes a copy of nvl and updates nvlp to point
190       to the copy.
191
192
193       The   nvlist_xdup()   function   differs   from  nvlist_dup()  in  that
194       nvlist_xdup() can use a different allocator.
195
196
197       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
203
204       The nvlist_lookup_nv_alloc() function  retrieves  the  pointer  to  the
205       allocator used when manipulating a name-value pair list.
206
207   PLUGGABLE ALLOCATORS
208       Using Pluggable Allocators:
209
210
211       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
215
216       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
221
222       The nva argument must be  passed  to  nvlist_xalloc(),  nvlist_xpack(),
223       nvlist_xunpack() and nvlist_xdup().
224
225
226       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
230
231       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
235
236       The  disposition  of the allocated objects and the memory used to store
237       them is left to the allocator implementation.
238
239
240       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
244         o  nv_alloc_nosleep
245         o  nv_alloc_sleep
246
247
248
249       The nvpair framework provides a fixed-buffer allocator, accessible  via
250       nv_fixed_ops.
251
252         o  nv_fixed_ops
253
254
255
256       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
261
262       Memory freed using nvlist_free(), pair-removal, or similar routines  is
263       not reclaimed.
264
265
266       When  used  to  initialize  the  fixed-buffer  allocator, nv_alloc_init
267       should be called as follows:
268
269         int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
270             void *bufptr, size_t sz);
271
272
273
274       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
278   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
283         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
289
290
291       The nva argument of the allocator implementation is  always  the  first
292       argument.
293
294
295       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
300
301       The optional (*nv_ao_fini()) function is responsible for the cleanup of
302       the allocator implementation. It is called by nv_alloc_fini().
303
304
305       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
309
310       The optional (*nv_ao_reset()) function is responsible for resetting the
311       nva_arg argument to the data specified by nv_alloc_init().
312
313
314       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
319
320       The  disposition  of the allocated objects and the memory used to store
321       them is left to the allocator implementation.
322

RETURN VALUES

324       For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():
325
326       0         success
327
328
329       EINVAL    invalid argument
330
331
332       ENOMEM    insufficient memory
333
334
335
336       For nvlist_pack(),  nvlist_unpack(),  nvlist_xpack(),  and  nvlist_xun‐
337       pack():
338
339       0          success
340
341
342       EINVAL     invalid argument
343
344
345       ENOMEM     insufficient memory
346
347
348       EFAULT     encode/decode error
349
350
351       ENOTSUP    encode/decode method not supported
352
353
354
355       For nvlist_size():
356
357       0         success
358
359
360       EINVAL    invalid argument
361
362
363
364       For nvlist_lookup_nv_alloc():
365
366
367       pointer to the allocator
368

USAGE

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

EXAMPLES

376           /*
377            * using the fixed-buffer allocator.
378            */
379            #include <sys/nvpair.h>
380
381           /* initialize the nvpair allocator framework */
382           static nv_alloc_t *
383           init(char *buf, size_t size)
384           {
385                nv_alloc_t *nvap;
386
387                if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
388                    return (NULL);
389
390                if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
391                    return (nvap);
392
393                return (NULL);
394            }
395
396            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
408                if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
409                     return (-1);
410
411                if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
412                     error = send_nvl(nvl);
413
414                nvlist_free(nvl);
415                return (error);
416               }
417
418

CONTEXT

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
424
425       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
431
432       These functions can be called from user  or  kernel  context  with  any
433       valid flag.
434
435
436
437SunOS 5.11                        16 Jan 2006                 nvlist_alloc(9F)
Impressum