Deleted Added
sdiff udiff text old ( 286642 ) new ( 286796 )
full compact
nv.9 (286642) nv.9 (286796)
1.\"
2.\" Copyright (c) 2013 The FreeBSD Foundation
1.\"
2.\" Copyright (c) 2013 The FreeBSD Foundation
3.\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
6.\" the FreeBSD Foundation.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:

--- 10 unchanged lines hidden (view full) ---

21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
4.\" All rights reserved.
5.\"
6.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
7.\" the FreeBSD Foundation.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:

--- 10 unchanged lines hidden (view full) ---

22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
29.\" $FreeBSD: head/share/man/man9/nv.9 286642 2015-08-11 17:41:32Z oshogbo $
30.\" $FreeBSD: head/share/man/man9/nv.9 286796 2015-08-15 06:34:49Z oshogbo $
30.\"
31.\"
31.Dd Aug 11, 2015
32.Dd August 15, 2015
32.Dt NV 9
33.Os
34.Sh NAME
35.Nm nvlist_create ,
36.Nm nvlist_destroy ,
37.Nm nvlist_error ,
38.Nm nvlist_set_error ,
39.Nm nvlist_empty ,

--- 4 unchanged lines hidden (view full) ---

44.Nm nvlist_dump ,
45.Nm nvlist_fdump ,
46.Nm nvlist_size ,
47.Nm nvlist_pack ,
48.Nm nvlist_unpack ,
49.Nm nvlist_send ,
50.Nm nvlist_recv ,
51.Nm nvlist_xfer ,
33.Dt NV 9
34.Os
35.Sh NAME
36.Nm nvlist_create ,
37.Nm nvlist_destroy ,
38.Nm nvlist_error ,
39.Nm nvlist_set_error ,
40.Nm nvlist_empty ,

--- 4 unchanged lines hidden (view full) ---

45.Nm nvlist_dump ,
46.Nm nvlist_fdump ,
47.Nm nvlist_size ,
48.Nm nvlist_pack ,
49.Nm nvlist_unpack ,
50.Nm nvlist_send ,
51.Nm nvlist_recv ,
52.Nm nvlist_xfer ,
53.Nm nvlist_in_array ,
52.Nm nvlist_next ,
53.Nm nvlist_add ,
54.Nm nvlist_move ,
55.Nm nvlist_get ,
56.Nm nvlist_take
57.Nd "library for name/value pairs"
58.Sh LIBRARY
59.Lb libnv

--- 6 unchanged lines hidden (view full) ---

66.Ft int
67.Fn nvlist_error "const nvlist_t *nvl"
68.Ft void
69.Fn nvlist_set_error "nvlist_t *nvl" "int error"
70.Ft bool
71.Fn nvlist_empty "const nvlist_t *nvl"
72.Ft int
73.Fn nvlist_flags "const nvlist_t *nvl"
54.Nm nvlist_next ,
55.Nm nvlist_add ,
56.Nm nvlist_move ,
57.Nm nvlist_get ,
58.Nm nvlist_take
59.Nd "library for name/value pairs"
60.Sh LIBRARY
61.Lb libnv

--- 6 unchanged lines hidden (view full) ---

68.Ft int
69.Fn nvlist_error "const nvlist_t *nvl"
70.Ft void
71.Fn nvlist_set_error "nvlist_t *nvl" "int error"
72.Ft bool
73.Fn nvlist_empty "const nvlist_t *nvl"
74.Ft int
75.Fn nvlist_flags "const nvlist_t *nvl"
76.Ft bool
77.Fn nvlist_in_array "const nvlist_t *nvl"
74.\"
75.Ft "nvlist_t *"
76.Fn nvlist_clone "const nvlist_t *nvl"
77.\"
78.Ft void
79.Fn nvlist_dump "const nvlist_t *nvl" "int fd"
80.Ft void
81.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp"

--- 28 unchanged lines hidden (view full) ---

110.Ft bool
111.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name"
112.Ft bool
113.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name"
114.Ft bool
115.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name"
116.Ft bool
117.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name"
78.\"
79.Ft "nvlist_t *"
80.Fn nvlist_clone "const nvlist_t *nvl"
81.\"
82.Ft void
83.Fn nvlist_dump "const nvlist_t *nvl" "int fd"
84.Ft void
85.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp"

--- 28 unchanged lines hidden (view full) ---

114.Ft bool
115.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name"
116.Ft bool
117.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name"
118.Ft bool
119.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name"
120.Ft bool
121.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name"
122.Ft bool
123.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name"
124.Ft bool
125.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name"
126.Ft bool
127.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name"
128.Ft bool
129.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name"
130.Ft bool
131.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name"
118.\"
119.Ft void
120.Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
121.Ft void
122.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value"
123.Ft void
124.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value"
125.Ft void
126.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value"
127.Ft void
128.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..."
129.Ft void
130.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap"
131.Ft void
132.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value"
133.Ft void
134.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value"
135.Ft void
136.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size"
132.\"
133.Ft void
134.Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
135.Ft void
136.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value"
137.Ft void
138.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value"
139.Ft void
140.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value"
141.Ft void
142.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..."
143.Ft void
144.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap"
145.Ft void
146.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value"
147.Ft void
148.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value"
149.Ft void
150.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size"
151.Ft void
152.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems"
153.
154.Ft void
155.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems"
156.
157.Ft void
158.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems"
159.
160.Ft void
161.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems"
162.
163.Ft void
164.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems"
137.\"
138.Ft void
139.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
140.Ft void
141.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value"
142.Ft void
143.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value"
144.Ft void
145.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size"
165.\"
166.Ft void
167.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
168.Ft void
169.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value"
170.Ft void
171.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value"
172.Ft void
173.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size"
174.Ft void
175.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems"
176.
177.Ft void
178.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems"
179.
180.Ft void
181.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems"
182.
183.Ft void
184.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems"
185.
186.Ft void
187.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems"
146.\"
147.Ft bool
148.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
149.Ft uint64_t
150.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name"
151.Ft "const char *"
152.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name"
153.Ft "const nvlist_t *"
154.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name"
155.Ft int
156.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name"
157.Ft "const void *"
158.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep"
188.\"
189.Ft bool
190.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
191.Ft uint64_t
192.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name"
193.Ft "const char *"
194.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name"
195.Ft "const nvlist_t *"
196.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name"
197.Ft int
198.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name"
199.Ft "const void *"
200.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep"
201.Ft "const bool *"
202.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
203.Ft "const uint64_t *"
204.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" "size_t *nitems"
205.Ft "const char * const *"
206.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" "size_t *nitems"
207.Ft "const nvlist_t * const *"
208.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "size_t *nitems"
209.Ft "const int *"
210.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
159.Ft "const nvlist_t *"
160.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
211.Ft "const nvlist_t *"
212.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
213.Ft "const nvlist_t *"
214.Fn nvlist_get_array_next "const nvlist_t *nvl"
215.Ft "const nvlist_t *"
216.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep"
161.\"
162.Ft bool
163.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
164.Ft uint64_t
165.Fn nvlist_take_number "nvlist_t *nvl" "const char *name"
166.Ft "char *"
167.Fn nvlist_take_string "nvlist_t *nvl" "const char *name"
168.Ft "nvlist_t *"
169.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name"
170.Ft int
171.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name"
172.Ft "void *"
173.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep"
217.\"
218.Ft bool
219.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
220.Ft uint64_t
221.Fn nvlist_take_number "nvlist_t *nvl" "const char *name"
222.Ft "char *"
223.Fn nvlist_take_string "nvlist_t *nvl" "const char *name"
224.Ft "nvlist_t *"
225.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name"
226.Ft int
227.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name"
228.Ft "void *"
229.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep"
230.Ft "bool *"
231.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
232.Ft "uint64_t **"
233.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" "size_t *nitems"
234.Ft "char **"
235.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" "size_t *nitems"
236.Ft "nvlist_t **"
237.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" "size_t *nitems"
238.Ft "int *"
239.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" "size_t *nitems"
174.\"
175.Ft void
176.Fn nvlist_free "nvlist_t *nvl" "const char *name"
177.Ft void
178.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type"
179.\"
180.Ft void
181.Fn nvlist_free_null "nvlist_t *nvl" "const char *name"

--- 4 unchanged lines hidden (view full) ---

186.Ft void
187.Fn nvlist_free_string "nvlist_t *nvl" "const char *name"
188.Ft void
189.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name"
190.Ft void
191.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
192.Ft void
193.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
240.\"
241.Ft void
242.Fn nvlist_free "nvlist_t *nvl" "const char *name"
243.Ft void
244.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type"
245.\"
246.Ft void
247.Fn nvlist_free_null "nvlist_t *nvl" "const char *name"

--- 4 unchanged lines hidden (view full) ---

252.Ft void
253.Fn nvlist_free_string "nvlist_t *nvl" "const char *name"
254.Ft void
255.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name"
256.Ft void
257.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
258.Ft void
259.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
260.Ft void
261.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name"
262.Ft void
263.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name"
264.Ft void
265.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name"
266.Ft void
267.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name"
268.Ft void
269.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name"
194.Sh DESCRIPTION
195The
196.Nm libnv
197library allows to easily manage name value pairs as well as send and receive
198them over sockets.
199A group (list) of name value pairs is called an
200.Nm nvlist .
201The API supports the following data types:

--- 14 unchanged lines hidden (view full) ---

216The value is a nested nvlist.
217.It Sy descriptor ( NV_TYPE_DESCRIPTOR )
218The value is a file descriptor.
219Note that file descriptors can be sent only over
220.Xr unix 4
221domain sockets.
222.It Sy binary ( NV_TYPE_BINARY )
223The value is a binary buffer.
270.Sh DESCRIPTION
271The
272.Nm libnv
273library allows to easily manage name value pairs as well as send and receive
274them over sockets.
275A group (list) of name value pairs is called an
276.Nm nvlist .
277The API supports the following data types:

--- 14 unchanged lines hidden (view full) ---

292The value is a nested nvlist.
293.It Sy descriptor ( NV_TYPE_DESCRIPTOR )
294The value is a file descriptor.
295Note that file descriptors can be sent only over
296.Xr unix 4
297domain sockets.
298.It Sy binary ( NV_TYPE_BINARY )
299The value is a binary buffer.
300.It Sy bool array ( NV_TYPE_BOOL_ARRAY )
301The value is an array of boolean values.
302.It Sy number array ( NV_TYPE_NUMBER_ARRAY )
303The value is an array of numbers, each stored as
304.Vt uint64_t .
305.It Sy string array ( NV_TYPE_STRING_ARRAY )
306The value is an array of C strings.
307.It Sy nvlist array ( NV_TYPE_NVLIST_ARRAY )
308The value is an array of nvlists.
309When an nvlist is added to an array, it becomes part of the primary nvlist.
310Traversing these arrays can be done using the
311.Fn nvlist_get_array_next
312and
313.Fn nvlist_get_pararr
314functions.
315.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY )
316The value is an array of files descriptors.
224.El
225.Pp
226The
227.Fn nvlist_create
228function allocates memory and initializes an nvlist.
229.Pp
230The following flag can be provided:
231.Pp

--- 43 unchanged lines hidden (view full) ---

275.Pp
276The
277.Fn nvlist_flags
278function returns flags used to create the nvlist with the
279.Fn nvlist_create
280function.
281.Pp
282The
317.El
318.Pp
319The
320.Fn nvlist_create
321function allocates memory and initializes an nvlist.
322.Pp
323The following flag can be provided:
324.Pp

--- 43 unchanged lines hidden (view full) ---

368.Pp
369The
370.Fn nvlist_flags
371function returns flags used to create the nvlist with the
372.Fn nvlist_create
373function.
374.Pp
375The
376.Fn nvlist_in_array
377function returns
378.Dv true
379if
380.Fa nvl
381is part of an array that is a member of another nvlist.
382.Pp
383The
283.Fn nvlist_clone
284functions clones the given nvlist.
285The clone shares no resources with its origin.
286This also means that all file descriptors that are part of the nvlist will be
287duplicated with the
288.Xr dup 2
289system call before placing them in the clone.
290.Pp

--- 150 unchanged lines hidden (view full) ---

441.Pp
442The
443.Fn nvlist_exists_null ,
444.Fn nvlist_exists_bool ,
445.Fn nvlist_exists_number ,
446.Fn nvlist_exists_string ,
447.Fn nvlist_exists_nvlist ,
448.Fn nvlist_exists_descriptor ,
384.Fn nvlist_clone
385functions clones the given nvlist.
386The clone shares no resources with its origin.
387This also means that all file descriptors that are part of the nvlist will be
388duplicated with the
389.Xr dup 2
390system call before placing them in the clone.
391.Pp

--- 150 unchanged lines hidden (view full) ---

542.Pp
543The
544.Fn nvlist_exists_null ,
545.Fn nvlist_exists_bool ,
546.Fn nvlist_exists_number ,
547.Fn nvlist_exists_string ,
548.Fn nvlist_exists_nvlist ,
549.Fn nvlist_exists_descriptor ,
449.Fn nvlist_exists_binary
550.Fn nvlist_exists_binary ,
551.Fn nvlist_exists_bool_array ,
552.Fn nvlist_exists_number_array ,
553.Fn nvlist_exists_string_array ,
554.Fn nvlist_exists_nvlist_array ,
555.Fn nvlist_exists_descriptor_array
450functions return
451.Dv true
452if element of the given name and the given type determined by the function name
453exists or
454.Dv false
455otherwise.
456The nvlist must not be in error state.
457.Pp
458The
459.Fn nvlist_add_null ,
460.Fn nvlist_add_bool ,
461.Fn nvlist_add_number ,
462.Fn nvlist_add_string ,
463.Fn nvlist_add_stringf ,
464.Fn nvlist_add_stringv ,
465.Fn nvlist_add_nvlist ,
466.Fn nvlist_add_descriptor ,
556functions return
557.Dv true
558if element of the given name and the given type determined by the function name
559exists or
560.Dv false
561otherwise.
562The nvlist must not be in error state.
563.Pp
564The
565.Fn nvlist_add_null ,
566.Fn nvlist_add_bool ,
567.Fn nvlist_add_number ,
568.Fn nvlist_add_string ,
569.Fn nvlist_add_stringf ,
570.Fn nvlist_add_stringv ,
571.Fn nvlist_add_nvlist ,
572.Fn nvlist_add_descriptor ,
467.Fn nvlist_add_binary
573.Fn nvlist_add_binary ,
574.Fn nvlist_add_bool_array ,
575.Fn nvlist_add_number_array ,
576.Fn nvlist_add_string_array ,
577.Fn nvlist_add_nvlist_array ,
578.Fn nvlist_add_descriptor_array
468functions add element to the given nvlist.
469When adding string or binary buffor the functions will allocate memory
470and copy the data over.
471When adding nvlist, the nvlist will be cloned and clone will be added.
472When adding descriptor, the descriptor will be duplicated using the
473.Xr dup 2
474system call and the new descriptor will be added.
579functions add element to the given nvlist.
580When adding string or binary buffor the functions will allocate memory
581and copy the data over.
582When adding nvlist, the nvlist will be cloned and clone will be added.
583When adding descriptor, the descriptor will be duplicated using the
584.Xr dup 2
585system call and the new descriptor will be added.
586The array functions will fail if there are any
587.Dv NULL
588elements in the array, or if the array pointer is
589.Dv NULL .
475If an error occurs while adding new element, internal error is set which can be
476examined using the
477.Fn nvlist_error
478function.
479.Pp
480The
481.Fn nvlist_move_string ,
482.Fn nvlist_move_nvlist ,
483.Fn nvlist_move_descriptor ,
590If an error occurs while adding new element, internal error is set which can be
591examined using the
592.Fn nvlist_error
593function.
594.Pp
595The
596.Fn nvlist_move_string ,
597.Fn nvlist_move_nvlist ,
598.Fn nvlist_move_descriptor ,
484.Fn nvlist_move_binary
599.Fn nvlist_move_binary ,
600.Fn nvlist_move_bool_array ,
601.Fn nvlist_move_number_array ,
602.Fn nvlist_move_string_array ,
603.Fn nvlist_move_nvlist_array ,
604.Fn nvlist_move_descriptor_array
485functions add new element to the given nvlist, but unlike
486.Fn nvlist_add_<type>
487functions they will consume the given resource.
605functions add new element to the given nvlist, but unlike
606.Fn nvlist_add_<type>
607functions they will consume the given resource.
608In the case of strings, descriptors, or nvlists every elements must be
609unique, or it could cause a double free.
610The array functions will fail if there are any
611.Dv NULL
612elements, or if the array pointer is
613.Dv NULL .
488If an error occurs while adding new element, the resource is destroyed and
489internal error is set which can be examined using the
490.Fn nvlist_error
491function.
492.Pp
493The
494.Fn nvlist_get_bool ,
495.Fn nvlist_get_number ,
496.Fn nvlist_get_string ,
497.Fn nvlist_get_nvlist ,
498.Fn nvlist_get_descriptor ,
614If an error occurs while adding new element, the resource is destroyed and
615internal error is set which can be examined using the
616.Fn nvlist_error
617function.
618.Pp
619The
620.Fn nvlist_get_bool ,
621.Fn nvlist_get_number ,
622.Fn nvlist_get_string ,
623.Fn nvlist_get_nvlist ,
624.Fn nvlist_get_descriptor ,
499.Fn nvlist_get_binary
500functions allow to obtain value of the given name.
501In case of string, nvlist, descriptor or binary, returned resource should
502not be modified - it still belongs to the nvlist.
503If element of the given name does not exist, the program will be aborted.
504To avoid that the caller should check for existence before trying to obtain
505the value or use
625.Fn nvlist_get_binary ,
626.Fn nvlist_get_bool_array ,
627.Fn nvlist_get_number_array ,
628.Fn nvlist_get_string_array ,
629.Fn nvlist_get_nvlist_array ,
630.Fn nvlist_get_descriptor_array
631functions return the value that corresponds to the given key name.
632In the case of strings, nvlists, descriptors, binary, or arrays, the returned
633resource should not be modified - they still belong to the nvlist.
634If an element of the given name does not exist, the program will be aborted.
635To avoid this, the caller should check for the existence of the name before
636trying to obtain the value, or use the
506.Xr dnvlist 3
637.Xr dnvlist 3
507extension, which allows to provide default value for a missing element.
638extension, which can provide a default value in the case of a missing element.
508The nvlist must not be in error state.
509.Pp
510The
511.Fn nvlist_get_parent
639The nvlist must not be in error state.
640.Pp
641The
642.Fn nvlist_get_parent
512function allows to obtain the parent nvlist from the nested nvlist.
643function returns the parent nvlist of the nested nvlist.
513.Pp
514The
644.Pp
645The
646.Fn nvlist_get_array_next
647function returns the next element from the array or
648.Dv NULL
649if the nvlist is not in array or it is the last element.
650Note that
651.Fn nvlist_get_array_next
652only works if you added the nvlist array using the
653.Fn nvlist_move_nvlist_array
654or
655.Fn nvlist_add_nvlist_array
656functions.
657.Pp
658The
659.Fn nvlist_get_pararr
660function returns the next element in the array, or if not available
661the parent of the nested nvlist.
662.Pp
663The
515.Fn nvlist_take_bool ,
516.Fn nvlist_take_number ,
517.Fn nvlist_take_string ,
518.Fn nvlist_take_nvlist ,
519.Fn nvlist_take_descriptor ,
664.Fn nvlist_take_bool ,
665.Fn nvlist_take_number ,
666.Fn nvlist_take_string ,
667.Fn nvlist_take_nvlist ,
668.Fn nvlist_take_descriptor ,
520.Fn nvlist_take_binary
669.Fn nvlist_take_binary ,
670.Fn nvlist_take_bool_array ,
671.Fn nvlist_take_number_array ,
672.Fn nvlist_take_string_array ,
673.Fn nvlist_take_nvlist_array ,
674.Fn nvlist_take_descriptor_array
521functions return value associated with the given name and remove the element
522from the nvlist.
523In case of string and binary values, the caller is responsible for free returned
524memory using the
525.Xr free 3
526function.
527In case of nvlist, the caller is responsible for destroying returned nvlist
528using the
529.Fn nvlist_destroy
530function.
531In case of descriptor, the caller is responsible for closing returned descriptor
532using the
533.Fn close 2
534system call.
675functions return value associated with the given name and remove the element
676from the nvlist.
677In case of string and binary values, the caller is responsible for free returned
678memory using the
679.Xr free 3
680function.
681In case of nvlist, the caller is responsible for destroying returned nvlist
682using the
683.Fn nvlist_destroy
684function.
685In case of descriptor, the caller is responsible for closing returned descriptor
686using the
687.Fn close 2
688system call.
535If element of the given name does not exist, the program will be aborted.
536To avoid that the caller should check for existence before trying to obtain
537the value or use
689If an element of the given name does not exist, the program will be aborted.
690To avoid that the caller should check for the existence of the given name
691before trying to obtain the value, or use the
538.Xr dnvlist 3
692.Xr dnvlist 3
539extension, which allows to provide default value for a missing element.
693extension, which can provide a default value in the case of a missing element.
694In the case of an array of strings or binary values, the caller is responsible
695for freeing every element of the array using the
696.Xr free 3
697function.
698In the case of an array of nvlists, the caller is responsible for destroying
699every element of array using the
700.Fn nvlist_destroy
701function.
702In the case of descriptors, the caller is responsible for closing every
703element of array using the
704.Fn close 2
705system call.
706In every case involving an array, the caller must also free the pointer to
707the array using the
708.Xr free 3
709function.
540The nvlist must not be in error state.
541.Pp
542The
543.Fn nvlist_free
544function removes element of the given name from the nvlist (besides of its type)
545and frees all resources associated with it.
546If element of the given name does not exist, the program will be aborted.
547The nvlist must not be in error state.

--- 8 unchanged lines hidden (view full) ---

556.Pp
557The
558.Fn nvlist_free_null ,
559.Fn nvlist_free_bool ,
560.Fn nvlist_free_number ,
561.Fn nvlist_free_string ,
562.Fn nvlist_free_nvlist ,
563.Fn nvlist_free_descriptor ,
710The nvlist must not be in error state.
711.Pp
712The
713.Fn nvlist_free
714function removes element of the given name from the nvlist (besides of its type)
715and frees all resources associated with it.
716If element of the given name does not exist, the program will be aborted.
717The nvlist must not be in error state.

--- 8 unchanged lines hidden (view full) ---

726.Pp
727The
728.Fn nvlist_free_null ,
729.Fn nvlist_free_bool ,
730.Fn nvlist_free_number ,
731.Fn nvlist_free_string ,
732.Fn nvlist_free_nvlist ,
733.Fn nvlist_free_descriptor ,
564.Fn nvlist_free_binary
734.Fn nvlist_free_binary ,
735.Fn nvlist_free_bool_array ,
736.Fn nvlist_free_number_array ,
737.Fn nvlist_free_string_array ,
738.Fn nvlist_free_nvlist_array ,
739.Fn nvlist_free_descriptor_array
565functions remove element of the given name and the given type determined by the
566function name from the nvlist and free all resources associated with it.
567If element of the given name and the given type does not exist, the program
568will be aborted.
569The nvlist must not be in error state.
570.Sh EXAMPLES
571The following example demonstrates how to prepare an nvlist and send it over
572.Xr unix 4

--- 101 unchanged lines hidden (view full) ---

674 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
675 if (type == NV_TYPE_NVLIST) {
676 nvl = nvlist_get_nvlist(nvl, name);
677 cookie = NULL;
678 }
679 }
680} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
681.Ed
740functions remove element of the given name and the given type determined by the
741function name from the nvlist and free all resources associated with it.
742If element of the given name and the given type does not exist, the program
743will be aborted.
744The nvlist must not be in error state.
745.Sh EXAMPLES
746The following example demonstrates how to prepare an nvlist and send it over
747.Xr unix 4

--- 101 unchanged lines hidden (view full) ---

849 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
850 if (type == NV_TYPE_NVLIST) {
851 nvl = nvlist_get_nvlist(nvl, name);
852 cookie = NULL;
853 }
854 }
855} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
856.Ed
857.Pp
858Iterating over every nested nvlist and every nvlist element:
859.Bd -literal
860nvlist_t *nvl;
861const nvlist_t * const *array;
862const char *name;
863void *cookie;
864int type;
865
866nvl = nvlist_recv(sock, 0);
867if (nvl == null)
868 err(1, "nvlist_recv() failed");
869
870cookie = null;
871do {
872 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
873 if (type == NV_TYPE_NVLIST) {
874 nvl = nvlist_get_nvlist(nvl, name);
875 cookie = NULL;
876 } else if (type == NV_TYPE_NVLIST_ARRAY) {
877 nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0];
878 cookie = NULL;
879 }
880 }
881} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL);
882.Ed
883.Pp
884Or alternatively:
885.Bd -literal
886nvlist_t *nvl, *tmp;
887const nvlist_t * const *array;
888const char *name;
889void *cookie;
890int type;
891
892nvl = nvlist_recv(sock, 0);
893if (nvl == null)
894 err(1, "nvlist_recv() failed");
895
896cooke = NULL;
897tmp = nvl;
898do {
899 do {
900 nvl = tmp;
901 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
902 if (type == NV_TYPE_NVLIST) {
903 nvl = nvlist_get_nvlist(nvl,
904 name);
905 cookie = NULL;
906 } else if (type == NV_TYPE_NVLIST_ARRAY) {
907 nvl = nvlist_get_nvlist_array(nvl, name,
908 NULL)[0];
909 cookie = NULL;
910 }
911 }
912 cookie = NULL;
913 } while ((tmp = nvlist_get_array_next(nvl)) != NULL);
914} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL);
915.Ed
682.Sh SEE ALSO
683.Xr close 2 ,
684.Xr dup 2 ,
685.Xr open 2 ,
686.Xr err 3 ,
687.Xr free 3 ,
688.Xr printf 3 ,
689.Xr unix 4

--- 12 unchanged lines hidden --- 		916.Sh SEE ALSO
917.Xr close 2 ,
918.Xr dup 2 ,
919.Xr open 2 ,
920.Xr err 3 ,
921.Xr free 3 ,
922.Xr printf 3 ,
923.Xr unix 4

--- 12 unchanged lines hidden ---