xref: /freebsd/share/man/man9/nv.9 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
158c86148SMariusz Zaborski.\"
258c86148SMariusz Zaborski.\" Copyright (c) 2013 The FreeBSD Foundation
3347a39b4SMariusz Zaborski.\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org>
458c86148SMariusz Zaborski.\" All rights reserved.
558c86148SMariusz Zaborski.\"
658c86148SMariusz Zaborski.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
758c86148SMariusz Zaborski.\" the FreeBSD Foundation.
858c86148SMariusz Zaborski.\"
958c86148SMariusz Zaborski.\" Redistribution and use in source and binary forms, with or without
1058c86148SMariusz Zaborski.\" modification, are permitted provided that the following conditions
1158c86148SMariusz Zaborski.\" are met:
1258c86148SMariusz Zaborski.\" 1. Redistributions of source code must retain the above copyright
1358c86148SMariusz Zaborski.\"    notice, this list of conditions and the following disclaimer.
1458c86148SMariusz Zaborski.\" 2. Redistributions in binary form must reproduce the above copyright
1558c86148SMariusz Zaborski.\"    notice, this list of conditions and the following disclaimer in the
1658c86148SMariusz Zaborski.\"    documentation and/or other materials provided with the distribution.
1758c86148SMariusz Zaborski.\"
1858c86148SMariusz Zaborski.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
1958c86148SMariusz Zaborski.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2058c86148SMariusz Zaborski.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2158c86148SMariusz Zaborski.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
2258c86148SMariusz Zaborski.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2358c86148SMariusz Zaborski.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
2458c86148SMariusz Zaborski.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2558c86148SMariusz Zaborski.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2658c86148SMariusz Zaborski.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2758c86148SMariusz Zaborski.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
2858c86148SMariusz Zaborski.\" SUCH DAMAGE.
2958c86148SMariusz Zaborski.\"
30*14ba7925SPawel Jakub Dawidek.Dd February 2, 2023
3158c86148SMariusz Zaborski.Dt NV 9
3258c86148SMariusz Zaborski.Os
3358c86148SMariusz Zaborski.Sh NAME
3458c86148SMariusz Zaborski.Nm nvlist_create ,
3558c86148SMariusz Zaborski.Nm nvlist_destroy ,
3658c86148SMariusz Zaborski.Nm nvlist_error ,
3758c86148SMariusz Zaborski.Nm nvlist_set_error ,
3858c86148SMariusz Zaborski.Nm nvlist_empty ,
3958c86148SMariusz Zaborski.Nm nvlist_flags ,
4058c86148SMariusz Zaborski.Nm nvlist_exists ,
4158c86148SMariusz Zaborski.Nm nvlist_free ,
4258c86148SMariusz Zaborski.Nm nvlist_clone ,
4358c86148SMariusz Zaborski.Nm nvlist_dump ,
4458c86148SMariusz Zaborski.Nm nvlist_fdump ,
4558c86148SMariusz Zaborski.Nm nvlist_size ,
4658c86148SMariusz Zaborski.Nm nvlist_pack ,
4758c86148SMariusz Zaborski.Nm nvlist_unpack ,
4858c86148SMariusz Zaborski.Nm nvlist_send ,
4958c86148SMariusz Zaborski.Nm nvlist_recv ,
5058c86148SMariusz Zaborski.Nm nvlist_xfer ,
51347a39b4SMariusz Zaborski.Nm nvlist_in_array ,
5258c86148SMariusz Zaborski.Nm nvlist_next ,
5358c86148SMariusz Zaborski.Nm nvlist_add ,
5458c86148SMariusz Zaborski.Nm nvlist_move ,
5558c86148SMariusz Zaborski.Nm nvlist_get ,
5624881c06SMariusz Zaborski.Nm nvlist_take ,
5724881c06SMariusz Zaborski.Nm nvlist_append
5858c86148SMariusz Zaborski.Nd "library for name/value pairs"
5958c86148SMariusz Zaborski.Sh LIBRARY
6058c86148SMariusz Zaborski.Lb libnv
6158c86148SMariusz Zaborski.Sh SYNOPSIS
62e98a6727SMark Johnston.In sys/nv.h
6358c86148SMariusz Zaborski.Ft "nvlist_t *"
6458c86148SMariusz Zaborski.Fn nvlist_create "int flags"
6558c86148SMariusz Zaborski.Ft void
6658c86148SMariusz Zaborski.Fn nvlist_destroy "nvlist_t *nvl"
6758c86148SMariusz Zaborski.Ft int
6858c86148SMariusz Zaborski.Fn nvlist_error "const nvlist_t *nvl"
6958c86148SMariusz Zaborski.Ft void
7098701874SChristian Brueffer.Fn nvlist_set_error "nvlist_t *nvl" "int error"
7158c86148SMariusz Zaborski.Ft bool
7258c86148SMariusz Zaborski.Fn nvlist_empty "const nvlist_t *nvl"
7358c86148SMariusz Zaborski.Ft int
7458c86148SMariusz Zaborski.Fn nvlist_flags "const nvlist_t *nvl"
75347a39b4SMariusz Zaborski.Ft bool
76347a39b4SMariusz Zaborski.Fn nvlist_in_array "const nvlist_t *nvl"
7758c86148SMariusz Zaborski.\"
7858c86148SMariusz Zaborski.Ft "nvlist_t *"
7958c86148SMariusz Zaborski.Fn nvlist_clone "const nvlist_t *nvl"
8058c86148SMariusz Zaborski.\"
8158c86148SMariusz Zaborski.Ft void
8298701874SChristian Brueffer.Fn nvlist_dump "const nvlist_t *nvl" "int fd"
8358c86148SMariusz Zaborski.Ft void
8498701874SChristian Brueffer.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp"
8558c86148SMariusz Zaborski.\"
8658c86148SMariusz Zaborski.Ft size_t
8758c86148SMariusz Zaborski.Fn nvlist_size "const nvlist_t *nvl"
8858c86148SMariusz Zaborski.Ft "void *"
8958c86148SMariusz Zaborski.Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep"
9058c86148SMariusz Zaborski.Ft "nvlist_t *"
9158c86148SMariusz Zaborski.Fn nvlist_unpack "const void *buf" "size_t size" "int flags"
9258c86148SMariusz Zaborski.\"
9358c86148SMariusz Zaborski.Ft int
9458c86148SMariusz Zaborski.Fn nvlist_send "int sock" "const nvlist_t *nvl"
9558c86148SMariusz Zaborski.Ft "nvlist_t *"
9658c86148SMariusz Zaborski.Fn nvlist_recv "int sock" "int flags"
9758c86148SMariusz Zaborski.Ft "nvlist_t *"
9858c86148SMariusz Zaborski.Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags"
9958c86148SMariusz Zaborski.\"
10058c86148SMariusz Zaborski.Ft "const char *"
10158c86148SMariusz Zaborski.Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep"
10258c86148SMariusz Zaborski.\"
10358c86148SMariusz Zaborski.Ft bool
10458c86148SMariusz Zaborski.Fn nvlist_exists "const nvlist_t *nvl" "const char *name"
10558c86148SMariusz Zaborski.Ft bool
10658c86148SMariusz Zaborski.Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type"
10758c86148SMariusz Zaborski.Ft bool
10858c86148SMariusz Zaborski.Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name"
10958c86148SMariusz Zaborski.Ft bool
11058c86148SMariusz Zaborski.Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name"
11158c86148SMariusz Zaborski.Ft bool
11258c86148SMariusz Zaborski.Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name"
11358c86148SMariusz Zaborski.Ft bool
11458c86148SMariusz Zaborski.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name"
11558c86148SMariusz Zaborski.Ft bool
11658c86148SMariusz Zaborski.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name"
11758c86148SMariusz Zaborski.Ft bool
11858c86148SMariusz Zaborski.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name"
11958c86148SMariusz Zaborski.Ft bool
12058c86148SMariusz Zaborski.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name"
121347a39b4SMariusz Zaborski.Ft bool
122347a39b4SMariusz Zaborski.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name"
123347a39b4SMariusz Zaborski.Ft bool
124347a39b4SMariusz Zaborski.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name"
125347a39b4SMariusz Zaborski.Ft bool
126347a39b4SMariusz Zaborski.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name"
127347a39b4SMariusz Zaborski.Ft bool
128347a39b4SMariusz Zaborski.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name"
129347a39b4SMariusz Zaborski.Ft bool
130347a39b4SMariusz Zaborski.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name"
13158c86148SMariusz Zaborski.\"
13258c86148SMariusz Zaborski.Ft void
13358c86148SMariusz Zaborski.Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
13458c86148SMariusz Zaborski.Ft void
13558c86148SMariusz Zaborski.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value"
13658c86148SMariusz Zaborski.Ft void
13758c86148SMariusz Zaborski.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value"
13858c86148SMariusz Zaborski.Ft void
13958c86148SMariusz Zaborski.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value"
14058c86148SMariusz Zaborski.Ft void
14158c86148SMariusz Zaborski.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..."
14258c86148SMariusz Zaborski.Ft void
14358c86148SMariusz Zaborski.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap"
14458c86148SMariusz Zaborski.Ft void
14558c86148SMariusz Zaborski.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value"
14658c86148SMariusz Zaborski.Ft void
14758c86148SMariusz Zaborski.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value"
14858c86148SMariusz Zaborski.Ft void
14958c86148SMariusz Zaborski.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size"
150347a39b4SMariusz Zaborski.Ft void
151347a39b4SMariusz Zaborski.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems"
152347a39b4SMariusz Zaborski.
153347a39b4SMariusz Zaborski.Ft void
154347a39b4SMariusz Zaborski.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems"
155347a39b4SMariusz Zaborski.
156347a39b4SMariusz Zaborski.Ft void
157347a39b4SMariusz Zaborski.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems"
158347a39b4SMariusz Zaborski.
159347a39b4SMariusz Zaborski.Ft void
160347a39b4SMariusz Zaborski.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems"
161347a39b4SMariusz Zaborski.
162347a39b4SMariusz Zaborski.Ft void
163347a39b4SMariusz Zaborski.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems"
16458c86148SMariusz Zaborski.\"
16558c86148SMariusz Zaborski.Ft void
16658c86148SMariusz Zaborski.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
16758c86148SMariusz Zaborski.Ft void
16858c86148SMariusz Zaborski.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value"
16958c86148SMariusz Zaborski.Ft void
17058c86148SMariusz Zaborski.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value"
17158c86148SMariusz Zaborski.Ft void
17258c86148SMariusz Zaborski.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size"
173347a39b4SMariusz Zaborski.Ft void
174347a39b4SMariusz Zaborski.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems"
175347a39b4SMariusz Zaborski.
176347a39b4SMariusz Zaborski.Ft void
177347a39b4SMariusz Zaborski.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems"
178347a39b4SMariusz Zaborski.
179347a39b4SMariusz Zaborski.Ft void
180347a39b4SMariusz Zaborski.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems"
181347a39b4SMariusz Zaborski.
182347a39b4SMariusz Zaborski.Ft void
183347a39b4SMariusz Zaborski.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems"
184347a39b4SMariusz Zaborski.
185347a39b4SMariusz Zaborski.Ft void
186347a39b4SMariusz Zaborski.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems"
18758c86148SMariusz Zaborski.\"
18858c86148SMariusz Zaborski.Ft bool
18958c86148SMariusz Zaborski.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
19058c86148SMariusz Zaborski.Ft uint64_t
19158c86148SMariusz Zaborski.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name"
19258c86148SMariusz Zaborski.Ft "const char *"
19358c86148SMariusz Zaborski.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name"
19458c86148SMariusz Zaborski.Ft "const nvlist_t *"
19558c86148SMariusz Zaborski.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name"
19658c86148SMariusz Zaborski.Ft int
19758c86148SMariusz Zaborski.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name"
19858c86148SMariusz Zaborski.Ft "const void *"
19958c86148SMariusz Zaborski.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep"
200347a39b4SMariusz Zaborski.Ft "const bool *"
201347a39b4SMariusz Zaborski.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
202347a39b4SMariusz Zaborski.Ft "const uint64_t *"
203a1b5ae33SMariusz Zaborski.Fn nvlist_get_number_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
204347a39b4SMariusz Zaborski.Ft "const char * const *"
205a1b5ae33SMariusz Zaborski.Fn nvlist_get_string_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
206347a39b4SMariusz Zaborski.Ft "const nvlist_t * const *"
207a1b5ae33SMariusz Zaborski.Fn nvlist_get_nvlist_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
208347a39b4SMariusz Zaborski.Ft "const int *"
209347a39b4SMariusz Zaborski.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
21058c86148SMariusz Zaborski.Ft "const nvlist_t *"
21158c86148SMariusz Zaborski.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
212347a39b4SMariusz Zaborski.Ft "const nvlist_t *"
213347a39b4SMariusz Zaborski.Fn nvlist_get_array_next "const nvlist_t *nvl"
214347a39b4SMariusz Zaborski.Ft "const nvlist_t *"
215347a39b4SMariusz Zaborski.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep"
21658c86148SMariusz Zaborski.\"
21758c86148SMariusz Zaborski.Ft bool
21858c86148SMariusz Zaborski.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
21958c86148SMariusz Zaborski.Ft uint64_t
22058c86148SMariusz Zaborski.Fn nvlist_take_number "nvlist_t *nvl" "const char *name"
22158c86148SMariusz Zaborski.Ft "char *"
22258c86148SMariusz Zaborski.Fn nvlist_take_string "nvlist_t *nvl" "const char *name"
22358c86148SMariusz Zaborski.Ft "nvlist_t *"
22458c86148SMariusz Zaborski.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name"
22558c86148SMariusz Zaborski.Ft int
22658c86148SMariusz Zaborski.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name"
22758c86148SMariusz Zaborski.Ft "void *"
22858c86148SMariusz Zaborski.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep"
229347a39b4SMariusz Zaborski.Ft "bool *"
230347a39b4SMariusz Zaborski.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
231347a39b4SMariusz Zaborski.Ft "uint64_t **"
232a1b5ae33SMariusz Zaborski.Fn nvlist_take_number_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
233347a39b4SMariusz Zaborski.Ft "char **"
234a1b5ae33SMariusz Zaborski.Fn nvlist_take_string_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
235347a39b4SMariusz Zaborski.Ft "nvlist_t **"
236a1b5ae33SMariusz Zaborski.Fn nvlist_take_nvlist_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
237347a39b4SMariusz Zaborski.Ft "int *"
238a1b5ae33SMariusz Zaborski.Fn nvlist_take_descriptor_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
23958c86148SMariusz Zaborski.\"
24058c86148SMariusz Zaborski.Ft void
24124881c06SMariusz Zaborski.Fn nvlist_append_bool_array "nvlist_t *nvl" "const char *name" "const bool value"
24224881c06SMariusz Zaborski.Ft void
24324881c06SMariusz Zaborski.Fn nvlist_append_number_array "nvlist_t *nvl" "const char *name" "const uint64_t value"
24424881c06SMariusz Zaborski.Ft void
24524881c06SMariusz Zaborski.Fn nvlist_append_string_array "nvlist_t *nvl" "const char *name" "const char * const value"
24624881c06SMariusz Zaborski.Ft void
24724881c06SMariusz Zaborski.Fn nvlist_append_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const value"
24824881c06SMariusz Zaborski.Ft void
24924881c06SMariusz Zaborski.Fn nvlist_append_descriptor_array "nvlist_t *nvl" "const char *name" "int value"
25024881c06SMariusz Zaborski.\"
25124881c06SMariusz Zaborski.Ft void
25258c86148SMariusz Zaborski.Fn nvlist_free "nvlist_t *nvl" "const char *name"
25358c86148SMariusz Zaborski.Ft void
25458c86148SMariusz Zaborski.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type"
25558c86148SMariusz Zaborski.\"
25658c86148SMariusz Zaborski.Ft void
25758c86148SMariusz Zaborski.Fn nvlist_free_null "nvlist_t *nvl" "const char *name"
25858c86148SMariusz Zaborski.Ft void
25958c86148SMariusz Zaborski.Fn nvlist_free_bool "nvlist_t *nvl" "const char *name"
26058c86148SMariusz Zaborski.Ft void
26158c86148SMariusz Zaborski.Fn nvlist_free_number "nvlist_t *nvl" "const char *name"
26258c86148SMariusz Zaborski.Ft void
26358c86148SMariusz Zaborski.Fn nvlist_free_string "nvlist_t *nvl" "const char *name"
26458c86148SMariusz Zaborski.Ft void
26558c86148SMariusz Zaborski.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name"
26658c86148SMariusz Zaborski.Ft void
26758c86148SMariusz Zaborski.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
26858c86148SMariusz Zaborski.Ft void
26958c86148SMariusz Zaborski.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
270347a39b4SMariusz Zaborski.Ft void
271347a39b4SMariusz Zaborski.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name"
272347a39b4SMariusz Zaborski.Ft void
273347a39b4SMariusz Zaborski.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name"
274347a39b4SMariusz Zaborski.Ft void
275347a39b4SMariusz Zaborski.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name"
276347a39b4SMariusz Zaborski.Ft void
277347a39b4SMariusz Zaborski.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name"
278347a39b4SMariusz Zaborski.Ft void
279347a39b4SMariusz Zaborski.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name"
28058c86148SMariusz Zaborski.Sh DESCRIPTION
28158c86148SMariusz ZaborskiThe
28258c86148SMariusz Zaborski.Nm libnv
28358c86148SMariusz Zaborskilibrary allows to easily manage name value pairs as well as send and receive
28458c86148SMariusz Zaborskithem over sockets.
28558c86148SMariusz ZaborskiA group (list) of name value pairs is called an
28658c86148SMariusz Zaborski.Nm nvlist .
28758c86148SMariusz ZaborskiThe API supports the following data types:
28858c86148SMariusz Zaborski.Bl -ohang -offset indent
28958c86148SMariusz Zaborski.It Sy null ( NV_TYPE_NULL )
29058c86148SMariusz ZaborskiThere is no data associated with the name.
29158c86148SMariusz Zaborski.It Sy bool ( NV_TYPE_BOOL )
29258c86148SMariusz ZaborskiThe value can be either
29358c86148SMariusz Zaborski.Dv true
29458c86148SMariusz Zaborskior
29558c86148SMariusz Zaborski.Dv false .
29658c86148SMariusz Zaborski.It Sy number ( NV_TYPE_NUMBER )
29758c86148SMariusz ZaborskiThe value is a number stored as
29858c86148SMariusz Zaborski.Vt uint64_t .
29958c86148SMariusz Zaborski.It Sy string ( NV_TYPE_STRING )
30058c86148SMariusz ZaborskiThe value is a C string.
30158c86148SMariusz Zaborski.It Sy nvlist ( NV_TYPE_NVLIST )
30258c86148SMariusz ZaborskiThe value is a nested nvlist.
30358c86148SMariusz Zaborski.It Sy descriptor ( NV_TYPE_DESCRIPTOR )
30458c86148SMariusz ZaborskiThe value is a file descriptor.
30558c86148SMariusz ZaborskiNote that file descriptors can be sent only over
30658c86148SMariusz Zaborski.Xr unix 4
30758c86148SMariusz Zaborskidomain sockets.
30858c86148SMariusz Zaborski.It Sy binary ( NV_TYPE_BINARY )
30958c86148SMariusz ZaborskiThe value is a binary buffer.
310347a39b4SMariusz Zaborski.It Sy bool array ( NV_TYPE_BOOL_ARRAY )
311347a39b4SMariusz ZaborskiThe value is an array of boolean values.
312347a39b4SMariusz Zaborski.It Sy number array ( NV_TYPE_NUMBER_ARRAY )
313347a39b4SMariusz ZaborskiThe value is an array of numbers, each stored as
314347a39b4SMariusz Zaborski.Vt uint64_t .
315347a39b4SMariusz Zaborski.It Sy string array ( NV_TYPE_STRING_ARRAY )
316347a39b4SMariusz ZaborskiThe value is an array of C strings.
317347a39b4SMariusz Zaborski.It Sy nvlist array  ( NV_TYPE_NVLIST_ARRAY )
318347a39b4SMariusz ZaborskiThe value is an array of nvlists.
319347a39b4SMariusz ZaborskiWhen an nvlist is added to an array, it becomes part of the primary nvlist.
320347a39b4SMariusz ZaborskiTraversing these arrays can be done using the
321347a39b4SMariusz Zaborski.Fn nvlist_get_array_next
322347a39b4SMariusz Zaborskiand
323347a39b4SMariusz Zaborski.Fn nvlist_get_pararr
324347a39b4SMariusz Zaborskifunctions.
325347a39b4SMariusz Zaborski.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY )
326347a39b4SMariusz ZaborskiThe value is an array of files descriptors.
32758c86148SMariusz Zaborski.El
32858c86148SMariusz Zaborski.Pp
32958c86148SMariusz ZaborskiThe
33058c86148SMariusz Zaborski.Fn nvlist_create
33158c86148SMariusz Zaborskifunction allocates memory and initializes an nvlist.
33258c86148SMariusz Zaborski.Pp
33358c86148SMariusz ZaborskiThe following flag can be provided:
33458c86148SMariusz Zaborski.Pp
33558c86148SMariusz Zaborski.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent
33658c86148SMariusz Zaborski.It Dv NV_FLAG_IGNORE_CASE
33758c86148SMariusz ZaborskiPerform case-insensitive lookups of provided names.
33858c86148SMariusz Zaborski.It Dv NV_FLAG_NO_UNIQUE
33958c86148SMariusz ZaborskiNames in the nvlist do not have to be unique.
34058c86148SMariusz Zaborski.El
34158c86148SMariusz Zaborski.Pp
34258c86148SMariusz ZaborskiThe
34358c86148SMariusz Zaborski.Fn nvlist_destroy
34458c86148SMariusz Zaborskifunction destroys the given nvlist.
34558c86148SMariusz ZaborskiFunction does nothing if
34658c86148SMariusz Zaborski.Dv NULL
34758c86148SMariusz Zaborskinvlist is provided.
34858c86148SMariusz ZaborskiFunction never modifies the
34958c86148SMariusz Zaborski.Va errno
35058c86148SMariusz Zaborskiglobal variable.
35158c86148SMariusz Zaborski.Pp
35258c86148SMariusz ZaborskiThe
35358c86148SMariusz Zaborski.Fn nvlist_error
35458c86148SMariusz Zaborskifunction returns any error value that the nvlist accumulated.
35558c86148SMariusz ZaborskiIf the given nvlist is
35658c86148SMariusz Zaborski.Dv NULL
35758c86148SMariusz Zaborskithe
35858c86148SMariusz Zaborski.Er ENOMEM
35958c86148SMariusz Zaborskierror will be returned.
36058c86148SMariusz Zaborski.Pp
36158c86148SMariusz ZaborskiThe
36258c86148SMariusz Zaborski.Fn nvlist_set_error
36358c86148SMariusz Zaborskifunction sets an nvlist to be in the error state.
36458c86148SMariusz ZaborskiSubsequent calls to
36558c86148SMariusz Zaborski.Fn nvlist_error
36658c86148SMariusz Zaborskiwill return the given error value.
36758c86148SMariusz ZaborskiThis function cannot be used to clear the error state from an nvlist.
36858c86148SMariusz ZaborskiThis function does nothing if the nvlist is already in the error state.
36958c86148SMariusz Zaborski.Pp
37058c86148SMariusz ZaborskiThe
37158c86148SMariusz Zaborski.Fn nvlist_empty
37258c86148SMariusz Zaborskifunction returns
37358c86148SMariusz Zaborski.Dv true
37458c86148SMariusz Zaborskiif the given nvlist is empty and
37558c86148SMariusz Zaborski.Dv false
37658c86148SMariusz Zaborskiotherwise.
37758c86148SMariusz ZaborskiThe nvlist must not be in error state.
37858c86148SMariusz Zaborski.Pp
37958c86148SMariusz ZaborskiThe
38058c86148SMariusz Zaborski.Fn nvlist_flags
38158c86148SMariusz Zaborskifunction returns flags used to create the nvlist with the
38258c86148SMariusz Zaborski.Fn nvlist_create
38358c86148SMariusz Zaborskifunction.
38458c86148SMariusz Zaborski.Pp
38558c86148SMariusz ZaborskiThe
386347a39b4SMariusz Zaborski.Fn nvlist_in_array
387347a39b4SMariusz Zaborskifunction returns
388347a39b4SMariusz Zaborski.Dv true
389347a39b4SMariusz Zaborskiif
390347a39b4SMariusz Zaborski.Fa nvl
391347a39b4SMariusz Zaborskiis part of an array that is a member of another nvlist.
392347a39b4SMariusz Zaborski.Pp
393347a39b4SMariusz ZaborskiThe
39458c86148SMariusz Zaborski.Fn nvlist_clone
39558c86148SMariusz Zaborskifunctions clones the given nvlist.
39658c86148SMariusz ZaborskiThe clone shares no resources with its origin.
39758c86148SMariusz ZaborskiThis also means that all file descriptors that are part of the nvlist will be
39858c86148SMariusz Zaborskiduplicated with the
39958c86148SMariusz Zaborski.Xr dup 2
40058c86148SMariusz Zaborskisystem call before placing them in the clone.
40158c86148SMariusz Zaborski.Pp
40258c86148SMariusz ZaborskiThe
40358c86148SMariusz Zaborski.Fn nvlist_dump
40458c86148SMariusz Zaborskidumps nvlist content for debugging purposes to the given file descriptor
40558c86148SMariusz Zaborski.Fa fd .
40658c86148SMariusz Zaborski.Pp
40758c86148SMariusz ZaborskiThe
40858c86148SMariusz Zaborski.Fn nvlist_fdump
40958c86148SMariusz Zaborskidumps nvlist content for debugging purposes to the given file stream
41058c86148SMariusz Zaborski.Fa fp .
41158c86148SMariusz Zaborski.Pp
41258c86148SMariusz ZaborskiThe
41358c86148SMariusz Zaborski.Fn nvlist_size
41458c86148SMariusz Zaborskifunction returns the size of the given nvlist after converting it to binary
41558c86148SMariusz Zaborskibuffer with the
41658c86148SMariusz Zaborski.Fn nvlist_pack
41758c86148SMariusz Zaborskifunction.
41858c86148SMariusz Zaborski.Pp
41958c86148SMariusz ZaborskiThe
42058c86148SMariusz Zaborski.Fn nvlist_pack
42158c86148SMariusz Zaborskifunction converts the given nvlist to a binary buffer.
42258c86148SMariusz ZaborskiThe function allocates memory for the buffer, which should be freed with the
42358c86148SMariusz Zaborski.Xr free 3
42458c86148SMariusz Zaborskifunction.
42558c86148SMariusz ZaborskiIf the
42658c86148SMariusz Zaborski.Fa sizep
42758c86148SMariusz Zaborskiargument is not
42858c86148SMariusz Zaborski.Dv NULL ,
42958c86148SMariusz Zaborskithe size of the buffer will be stored there.
43058c86148SMariusz ZaborskiThe function returns
43158c86148SMariusz Zaborski.Dv NULL
43258c86148SMariusz Zaborskiin case of an error (allocation failure).
43358c86148SMariusz ZaborskiIf the nvlist contains any file descriptors
43458c86148SMariusz Zaborski.Dv NULL
43558c86148SMariusz Zaborskiwill be returned.
43658c86148SMariusz ZaborskiThe nvlist must not be in error state.
43758c86148SMariusz Zaborski.Pp
43858c86148SMariusz ZaborskiThe
43958c86148SMariusz Zaborski.Fn nvlist_unpack
44058c86148SMariusz Zaborskifunction converts the given buffer to the nvlist.
44158c86148SMariusz ZaborskiThe
44258c86148SMariusz Zaborski.Fa flags
44358c86148SMariusz Zaborskiargument defines what type of the top level nvlist is expected to be.
44458c86148SMariusz ZaborskiFlags are set up using the
44558c86148SMariusz Zaborski.Fn nvlist_create
44658c86148SMariusz Zaborskifunction.
44758c86148SMariusz ZaborskiIf the nvlist flags do not match the flags passed to
44858c86148SMariusz Zaborski.Fn nvlist_unpack ,
44958c86148SMariusz Zaborskithe nvlist will not be returned.
45058c86148SMariusz ZaborskiEvery nested nvlist list should be checked using
45158c86148SMariusz Zaborski.Fn nvlist_flags
45258c86148SMariusz Zaborskifunction.
45358c86148SMariusz ZaborskiThe function returns
45458c86148SMariusz Zaborski.Dv NULL
45558c86148SMariusz Zaborskiin case of an error.
45658c86148SMariusz Zaborski.Pp
45758c86148SMariusz ZaborskiThe
45858c86148SMariusz Zaborski.Fn nvlist_send
45958c86148SMariusz Zaborskifunction sends the given nvlist over the socket given by the
46058c86148SMariusz Zaborski.Fa sock
46158c86148SMariusz Zaborskiargument.
46258c86148SMariusz ZaborskiNote that nvlist that contains file descriptors can only be send over
46358c86148SMariusz Zaborski.Xr unix 4
46458c86148SMariusz Zaborskidomain sockets.
46558c86148SMariusz Zaborski.Pp
46658c86148SMariusz ZaborskiThe
46758c86148SMariusz Zaborski.Fn nvlist_recv
46858c86148SMariusz Zaborskifunction receives nvlist over the socket given by the
46958c86148SMariusz Zaborski.Fa sock
47058c86148SMariusz Zaborskiargument.
47158c86148SMariusz ZaborskiThe
47258c86148SMariusz Zaborski.Fa flags
47358c86148SMariusz Zaborskiargument defines what type of the top level nvlist is expected to be.
47458c86148SMariusz ZaborskiFlags are set up using the
47558c86148SMariusz Zaborski.Fn nvlist_create
47658c86148SMariusz Zaborskifunction.
47758c86148SMariusz ZaborskiIf the nvlist flags do not match the flags passed to
47858c86148SMariusz Zaborski.Fn nvlist_recv ,
47958c86148SMariusz Zaborskithe nvlist will not be returned.
48058c86148SMariusz ZaborskiEvery nested nvlist list should be checked using
48158c86148SMariusz Zaborski.Fn nvlist_flags
48258c86148SMariusz Zaborskifunction.
48358c86148SMariusz Zaborski.Pp
48458c86148SMariusz ZaborskiThe
48558c86148SMariusz Zaborski.Fn nvlist_xfer
48658c86148SMariusz Zaborskifunction sends the given nvlist over the socket given by the
48758c86148SMariusz Zaborski.Fa sock
48858c86148SMariusz Zaborskiargument and receives nvlist over the same socket.
48958c86148SMariusz ZaborskiThe
49058c86148SMariusz Zaborski.Fa flags
49158c86148SMariusz Zaborskiargument defines what type of the top level nvlist is expected to be.
49258c86148SMariusz ZaborskiFlags are set up using the
49358c86148SMariusz Zaborski.Fn nvlist_create
49458c86148SMariusz Zaborskifunction.
49558c86148SMariusz ZaborskiIf the nvlist flags do not match the flags passed to
49658c86148SMariusz Zaborski.Fn nvlist_xfer ,
49758c86148SMariusz Zaborskithe nvlist will not be returned.
49858c86148SMariusz ZaborskiEvery nested nvlist list should be checked using
49958c86148SMariusz Zaborski.Fn nvlist_flags
50058c86148SMariusz Zaborskifunction.
50158c86148SMariusz ZaborskiThe given nvlist is always destroyed.
50258c86148SMariusz Zaborski.Pp
50358c86148SMariusz ZaborskiThe
50458c86148SMariusz Zaborski.Fn nvlist_next
50558c86148SMariusz Zaborskifunction iterates over the given nvlist returning names and types of subsequent
50658c86148SMariusz Zaborskielements.
50758c86148SMariusz ZaborskiThe
50858c86148SMariusz Zaborski.Fa cookiep
50958c86148SMariusz Zaborskiargument allows the function to figure out which element should be returned
51058c86148SMariusz Zaborskinext.
51158c86148SMariusz ZaborskiThe
51258c86148SMariusz Zaborski.Va *cookiep
51358c86148SMariusz Zaborskishould be set to
51458c86148SMariusz Zaborski.Dv NULL
51558c86148SMariusz Zaborskifor the first call and should not be changed later.
51658c86148SMariusz ZaborskiReturning
51758c86148SMariusz Zaborski.Dv NULL
51858c86148SMariusz Zaborskimeans there are no more elements on the nvlist.
51958c86148SMariusz ZaborskiThe
52058c86148SMariusz Zaborski.Fa typep
52158c86148SMariusz Zaborskiargument can be NULL.
52258c86148SMariusz ZaborskiElements may not be removed from the nvlist while traversing it.
52358c86148SMariusz ZaborskiThe nvlist must not be in error state.
52489ca10c6SMariusz ZaborskiNote that
52589ca10c6SMariusz Zaborski.Fn nvlist_next
52689ca10c6SMariusz Zaborskiwill handle
52789ca10c6SMariusz Zaborski.Va cookiep
52889ca10c6SMariusz Zaborskibeing set to
52989ca10c6SMariusz Zaborski.Dv NULL .
53089ca10c6SMariusz ZaborskiIn this case first element is returned or
53189ca10c6SMariusz Zaborski.Dv NULL
53289ca10c6SMariusz Zaborskiif nvlist is empty.
53389ca10c6SMariusz ZaborskiThis behavior simplifies removing the first element from the list.
53458c86148SMariusz Zaborski.Pp
53558c86148SMariusz ZaborskiThe
53658c86148SMariusz Zaborski.Fn nvlist_exists
53758c86148SMariusz Zaborskifunction returns
53858c86148SMariusz Zaborski.Dv true
53958c86148SMariusz Zaborskiif element of the given name exists (besides of its type) or
54058c86148SMariusz Zaborski.Dv false
54158c86148SMariusz Zaborskiotherwise.
54258c86148SMariusz ZaborskiThe nvlist must not be in error state.
54358c86148SMariusz Zaborski.Pp
54458c86148SMariusz ZaborskiThe
54558c86148SMariusz Zaborski.Fn nvlist_exists_type
54658c86148SMariusz Zaborskifunction returns
54758c86148SMariusz Zaborski.Dv true
54858c86148SMariusz Zaborskiif element of the given name and the given type exists or
54958c86148SMariusz Zaborski.Dv false
55058c86148SMariusz Zaborskiotherwise.
55158c86148SMariusz ZaborskiThe nvlist must not be in error state.
55258c86148SMariusz Zaborski.Pp
55358c86148SMariusz ZaborskiThe
55458c86148SMariusz Zaborski.Fn nvlist_exists_null ,
55558c86148SMariusz Zaborski.Fn nvlist_exists_bool ,
55658c86148SMariusz Zaborski.Fn nvlist_exists_number ,
55758c86148SMariusz Zaborski.Fn nvlist_exists_string ,
55858c86148SMariusz Zaborski.Fn nvlist_exists_nvlist ,
55958c86148SMariusz Zaborski.Fn nvlist_exists_descriptor ,
560347a39b4SMariusz Zaborski.Fn nvlist_exists_binary ,
561347a39b4SMariusz Zaborski.Fn nvlist_exists_bool_array ,
562347a39b4SMariusz Zaborski.Fn nvlist_exists_number_array ,
563347a39b4SMariusz Zaborski.Fn nvlist_exists_string_array ,
564347a39b4SMariusz Zaborski.Fn nvlist_exists_nvlist_array ,
565347a39b4SMariusz Zaborski.Fn nvlist_exists_descriptor_array
56658c86148SMariusz Zaborskifunctions return
56758c86148SMariusz Zaborski.Dv true
56858c86148SMariusz Zaborskiif element of the given name and the given type determined by the function name
56958c86148SMariusz Zaborskiexists or
57058c86148SMariusz Zaborski.Dv false
57158c86148SMariusz Zaborskiotherwise.
57258c86148SMariusz ZaborskiThe nvlist must not be in error state.
57358c86148SMariusz Zaborski.Pp
57458c86148SMariusz ZaborskiThe
57558c86148SMariusz Zaborski.Fn nvlist_add_null ,
57658c86148SMariusz Zaborski.Fn nvlist_add_bool ,
57758c86148SMariusz Zaborski.Fn nvlist_add_number ,
57858c86148SMariusz Zaborski.Fn nvlist_add_string ,
57958c86148SMariusz Zaborski.Fn nvlist_add_stringf ,
58058c86148SMariusz Zaborski.Fn nvlist_add_stringv ,
58158c86148SMariusz Zaborski.Fn nvlist_add_nvlist ,
58258c86148SMariusz Zaborski.Fn nvlist_add_descriptor ,
583347a39b4SMariusz Zaborski.Fn nvlist_add_binary ,
584347a39b4SMariusz Zaborski.Fn nvlist_add_bool_array ,
585347a39b4SMariusz Zaborski.Fn nvlist_add_number_array ,
586347a39b4SMariusz Zaborski.Fn nvlist_add_string_array ,
587347a39b4SMariusz Zaborski.Fn nvlist_add_nvlist_array ,
588347a39b4SMariusz Zaborski.Fn nvlist_add_descriptor_array
58958c86148SMariusz Zaborskifunctions add element to the given nvlist.
5901093ff61SMariusz ZaborskiWhen adding string or binary buffer the functions will allocate memory
59158c86148SMariusz Zaborskiand copy the data over.
59258c86148SMariusz ZaborskiWhen adding nvlist, the nvlist will be cloned and clone will be added.
59358c86148SMariusz ZaborskiWhen adding descriptor, the descriptor will be duplicated using the
59458c86148SMariusz Zaborski.Xr dup 2
59558c86148SMariusz Zaborskisystem call and the new descriptor will be added.
596347a39b4SMariusz ZaborskiThe array functions will fail if there are any
597347a39b4SMariusz Zaborski.Dv NULL
598347a39b4SMariusz Zaborskielements in the array, or if the array pointer is
599347a39b4SMariusz Zaborski.Dv NULL .
60058c86148SMariusz ZaborskiIf an error occurs while adding new element, internal error is set which can be
60158c86148SMariusz Zaborskiexamined using the
60258c86148SMariusz Zaborski.Fn nvlist_error
60358c86148SMariusz Zaborskifunction.
60458c86148SMariusz Zaborski.Pp
60558c86148SMariusz ZaborskiThe
60658c86148SMariusz Zaborski.Fn nvlist_move_string ,
60758c86148SMariusz Zaborski.Fn nvlist_move_nvlist ,
60858c86148SMariusz Zaborski.Fn nvlist_move_descriptor ,
609347a39b4SMariusz Zaborski.Fn nvlist_move_binary ,
610347a39b4SMariusz Zaborski.Fn nvlist_move_bool_array ,
611347a39b4SMariusz Zaborski.Fn nvlist_move_number_array ,
612347a39b4SMariusz Zaborski.Fn nvlist_move_string_array ,
613347a39b4SMariusz Zaborski.Fn nvlist_move_nvlist_array ,
614347a39b4SMariusz Zaborski.Fn nvlist_move_descriptor_array
61558c86148SMariusz Zaborskifunctions add new element to the given nvlist, but unlike
61658c86148SMariusz Zaborski.Fn nvlist_add_<type>
61758c86148SMariusz Zaborskifunctions they will consume the given resource.
618347a39b4SMariusz ZaborskiIn the case of strings, descriptors, or nvlists every elements must be
619347a39b4SMariusz Zaborskiunique, or it could cause a double free.
620347a39b4SMariusz ZaborskiThe array functions will fail if there are any
621347a39b4SMariusz Zaborski.Dv NULL
622347a39b4SMariusz Zaborskielements, or if the array pointer is
623347a39b4SMariusz Zaborski.Dv NULL .
62458c86148SMariusz ZaborskiIf an error occurs while adding new element, the resource is destroyed and
62558c86148SMariusz Zaborskiinternal error is set which can be examined using the
62658c86148SMariusz Zaborski.Fn nvlist_error
62758c86148SMariusz Zaborskifunction.
62858c86148SMariusz Zaborski.Pp
62958c86148SMariusz ZaborskiThe
63058c86148SMariusz Zaborski.Fn nvlist_get_bool ,
63158c86148SMariusz Zaborski.Fn nvlist_get_number ,
63258c86148SMariusz Zaborski.Fn nvlist_get_string ,
63358c86148SMariusz Zaborski.Fn nvlist_get_nvlist ,
63458c86148SMariusz Zaborski.Fn nvlist_get_descriptor ,
635347a39b4SMariusz Zaborski.Fn nvlist_get_binary ,
636347a39b4SMariusz Zaborski.Fn nvlist_get_bool_array ,
637347a39b4SMariusz Zaborski.Fn nvlist_get_number_array ,
638347a39b4SMariusz Zaborski.Fn nvlist_get_string_array ,
639347a39b4SMariusz Zaborski.Fn nvlist_get_nvlist_array ,
640347a39b4SMariusz Zaborski.Fn nvlist_get_descriptor_array
641347a39b4SMariusz Zaborskifunctions return the value that corresponds to the given key name.
642347a39b4SMariusz ZaborskiIn the case of strings, nvlists, descriptors, binary, or arrays, the returned
643347a39b4SMariusz Zaborskiresource should not be modified - they still belong to the nvlist.
644347a39b4SMariusz ZaborskiIf an element of the given name does not exist, the program will be aborted.
645347a39b4SMariusz ZaborskiTo avoid this, the caller should check for the existence of the name before
646347a39b4SMariusz Zaborskitrying to obtain the value, or use the
64758c86148SMariusz Zaborski.Xr dnvlist 3
648347a39b4SMariusz Zaborskiextension, which can provide a default value in the case of a missing element.
64958c86148SMariusz ZaborskiThe nvlist must not be in error state.
65058c86148SMariusz Zaborski.Pp
65158c86148SMariusz ZaborskiThe
65258c86148SMariusz Zaborski.Fn nvlist_get_parent
653347a39b4SMariusz Zaborskifunction returns the parent nvlist of the nested nvlist.
654347a39b4SMariusz Zaborski.Pp
655347a39b4SMariusz ZaborskiThe
656347a39b4SMariusz Zaborski.Fn nvlist_get_array_next
657347a39b4SMariusz Zaborskifunction returns the next element from the array or
658347a39b4SMariusz Zaborski.Dv NULL
659347a39b4SMariusz Zaborskiif the nvlist is not in array or it is the last element.
660347a39b4SMariusz ZaborskiNote that
661347a39b4SMariusz Zaborski.Fn nvlist_get_array_next
662347a39b4SMariusz Zaborskionly works if you added the nvlist array using the
663347a39b4SMariusz Zaborski.Fn nvlist_move_nvlist_array
664347a39b4SMariusz Zaborskior
665347a39b4SMariusz Zaborski.Fn nvlist_add_nvlist_array
666347a39b4SMariusz Zaborskifunctions.
667347a39b4SMariusz Zaborski.Pp
668347a39b4SMariusz ZaborskiThe
669347a39b4SMariusz Zaborski.Fn nvlist_get_pararr
670347a39b4SMariusz Zaborskifunction returns the next element in the array, or if not available
671347a39b4SMariusz Zaborskithe parent of the nested nvlist.
67258c86148SMariusz Zaborski.Pp
67358c86148SMariusz ZaborskiThe
67458c86148SMariusz Zaborski.Fn nvlist_take_bool ,
67558c86148SMariusz Zaborski.Fn nvlist_take_number ,
67658c86148SMariusz Zaborski.Fn nvlist_take_string ,
67758c86148SMariusz Zaborski.Fn nvlist_take_nvlist ,
67858c86148SMariusz Zaborski.Fn nvlist_take_descriptor ,
679347a39b4SMariusz Zaborski.Fn nvlist_take_binary ,
680347a39b4SMariusz Zaborski.Fn nvlist_take_bool_array ,
681347a39b4SMariusz Zaborski.Fn nvlist_take_number_array ,
682347a39b4SMariusz Zaborski.Fn nvlist_take_string_array ,
683347a39b4SMariusz Zaborski.Fn nvlist_take_nvlist_array ,
684347a39b4SMariusz Zaborski.Fn nvlist_take_descriptor_array
68558c86148SMariusz Zaborskifunctions return value associated with the given name and remove the element
68658c86148SMariusz Zaborskifrom the nvlist.
68758c86148SMariusz ZaborskiIn case of string and binary values, the caller is responsible for free returned
68858c86148SMariusz Zaborskimemory using the
68958c86148SMariusz Zaborski.Xr free 3
69058c86148SMariusz Zaborskifunction.
69158c86148SMariusz ZaborskiIn case of nvlist, the caller is responsible for destroying returned nvlist
69258c86148SMariusz Zaborskiusing the
69358c86148SMariusz Zaborski.Fn nvlist_destroy
69458c86148SMariusz Zaborskifunction.
69558c86148SMariusz ZaborskiIn case of descriptor, the caller is responsible for closing returned descriptor
69658c86148SMariusz Zaborskiusing the
69758c86148SMariusz Zaborski.Fn close 2
69858c86148SMariusz Zaborskisystem call.
699347a39b4SMariusz ZaborskiIf an element of the given name does not exist, the program will be aborted.
700347a39b4SMariusz ZaborskiTo avoid that the caller should check for the existence of the given name
701347a39b4SMariusz Zaborskibefore trying to obtain the value, or use the
70258c86148SMariusz Zaborski.Xr dnvlist 3
703347a39b4SMariusz Zaborskiextension, which can provide a default value in the case of a missing element.
704347a39b4SMariusz ZaborskiIn the case of an array of strings or binary values, the caller is responsible
705347a39b4SMariusz Zaborskifor freeing every element of the array using the
706347a39b4SMariusz Zaborski.Xr free 3
707347a39b4SMariusz Zaborskifunction.
708347a39b4SMariusz ZaborskiIn the case of an array of nvlists, the caller is responsible for destroying
709347a39b4SMariusz Zaborskievery element of array using the
710347a39b4SMariusz Zaborski.Fn nvlist_destroy
711347a39b4SMariusz Zaborskifunction.
712347a39b4SMariusz ZaborskiIn the case of descriptors, the caller is responsible for closing every
713347a39b4SMariusz Zaborskielement of array using the
714347a39b4SMariusz Zaborski.Fn close 2
715347a39b4SMariusz Zaborskisystem call.
716347a39b4SMariusz ZaborskiIn every case involving an array, the caller must also free the pointer to
717347a39b4SMariusz Zaborskithe array using the
718347a39b4SMariusz Zaborski.Xr free 3
719347a39b4SMariusz Zaborskifunction.
72058c86148SMariusz ZaborskiThe nvlist must not be in error state.
72158c86148SMariusz Zaborski.Pp
72258c86148SMariusz ZaborskiThe
72324881c06SMariusz Zaborski.Fn nvlist_append_bool_array ,
72424881c06SMariusz Zaborski.Fn nvlist_append_number_array ,
72524881c06SMariusz Zaborski.Fn nvlist_append_string_array ,
72624881c06SMariusz Zaborski.Fn nvlist_append_nvlist_array ,
72724881c06SMariusz Zaborski.Fn nvlist_append_descriptor_array
72824881c06SMariusz Zaborskifunctions append an element to the existing array using the same semantics
72924881c06SMariusz Zaborskias the add functions (i.e. the element will be copied when applicable).
73024881c06SMariusz ZaborskiIf the array for a given key does not exist, then it will be created
73124881c06SMariusz Zaborskias if using the
73224881c06SMariusz Zaborski.Fn nvlist_add_<type>_array
73324881c06SMariusz Zaborskifunction.
73424881c06SMariusz ZaborskiThe internal error is set on append failure.
73524881c06SMariusz Zaborski.Pp
73624881c06SMariusz ZaborskiThe
73758c86148SMariusz Zaborski.Fn nvlist_free
73858c86148SMariusz Zaborskifunction removes element of the given name from the nvlist (besides of its type)
73958c86148SMariusz Zaborskiand frees all resources associated with it.
74058c86148SMariusz ZaborskiIf element of the given name does not exist, the program will be aborted.
74158c86148SMariusz ZaborskiThe nvlist must not be in error state.
74258c86148SMariusz Zaborski.Pp
74358c86148SMariusz ZaborskiThe
74458c86148SMariusz Zaborski.Fn nvlist_free_type
74558c86148SMariusz Zaborskifunction removes element of the given name and the given type from the nvlist
74658c86148SMariusz Zaborskiand frees all resources associated with it.
74758c86148SMariusz ZaborskiIf element of the given name and the given type does not exist, the program
74858c86148SMariusz Zaborskiwill be aborted.
74958c86148SMariusz ZaborskiThe nvlist must not be in error state.
75058c86148SMariusz Zaborski.Pp
75158c86148SMariusz ZaborskiThe
75258c86148SMariusz Zaborski.Fn nvlist_free_null ,
75358c86148SMariusz Zaborski.Fn nvlist_free_bool ,
75458c86148SMariusz Zaborski.Fn nvlist_free_number ,
75558c86148SMariusz Zaborski.Fn nvlist_free_string ,
75658c86148SMariusz Zaborski.Fn nvlist_free_nvlist ,
75758c86148SMariusz Zaborski.Fn nvlist_free_descriptor ,
758347a39b4SMariusz Zaborski.Fn nvlist_free_binary ,
759347a39b4SMariusz Zaborski.Fn nvlist_free_bool_array ,
760347a39b4SMariusz Zaborski.Fn nvlist_free_number_array ,
761347a39b4SMariusz Zaborski.Fn nvlist_free_string_array ,
762347a39b4SMariusz Zaborski.Fn nvlist_free_nvlist_array ,
763347a39b4SMariusz Zaborski.Fn nvlist_free_descriptor_array
76458c86148SMariusz Zaborskifunctions remove element of the given name and the given type determined by the
76558c86148SMariusz Zaborskifunction name from the nvlist and free all resources associated with it.
76658c86148SMariusz ZaborskiIf element of the given name and the given type does not exist, the program
76758c86148SMariusz Zaborskiwill be aborted.
76858c86148SMariusz ZaborskiThe nvlist must not be in error state.
7691093ff61SMariusz Zaborski.Sh NOTES
7701093ff61SMariusz ZaborskiThe
7711093ff61SMariusz Zaborski.Fn nvlist_pack
7721093ff61SMariusz Zaborskiand
7731093ff61SMariusz Zaborski.Fn nvlist_unpack
7741093ff61SMariusz Zaborskifunctions handle the byte-order conversions, so the binary buffer can be
7751093ff61SMariusz Zaborskipacked/unpacked by the hosts with the different endianness.
77658c86148SMariusz Zaborski.Sh EXAMPLES
77758c86148SMariusz ZaborskiThe following example demonstrates how to prepare an nvlist and send it over
77858c86148SMariusz Zaborski.Xr unix 4
77958c86148SMariusz Zaborskidomain socket.
78058c86148SMariusz Zaborski.Bd -literal
78158c86148SMariusz Zaborskinvlist_t *nvl;
78258c86148SMariusz Zaborskiint fd;
78358c86148SMariusz Zaborski
78458c86148SMariusz Zaborskifd = open("/tmp/foo", O_RDONLY);
78558c86148SMariusz Zaborskiif (fd < 0)
78658c86148SMariusz Zaborski        err(1, "open(\\"/tmp/foo\\") failed");
78758c86148SMariusz Zaborski
78858c86148SMariusz Zaborskinvl = nvlist_create(0);
78958c86148SMariusz Zaborski/*
79058c86148SMariusz Zaborski * There is no need to check if nvlist_create() succeeded,
79158c86148SMariusz Zaborski * as the nvlist_add_<type>() functions can cope.
79258c86148SMariusz Zaborski * If it failed, nvlist_send() will fail.
79358c86148SMariusz Zaborski */
79458c86148SMariusz Zaborskinvlist_add_string(nvl, "filename", "/tmp/foo");
79558c86148SMariusz Zaborskinvlist_add_number(nvl, "flags", O_RDONLY);
79658c86148SMariusz Zaborski/*
79758c86148SMariusz Zaborski * We just want to send the descriptor, so we can give it
79858c86148SMariusz Zaborski * for the nvlist to consume (that's why we use nvlist_move
79958c86148SMariusz Zaborski * not nvlist_add).
80058c86148SMariusz Zaborski */
80158c86148SMariusz Zaborskinvlist_move_descriptor(nvl, "fd", fd);
80258c86148SMariusz Zaborskiif (nvlist_send(sock, nvl) < 0) {
80358c86148SMariusz Zaborski	nvlist_destroy(nvl);
80458c86148SMariusz Zaborski	err(1, "nvlist_send() failed");
80558c86148SMariusz Zaborski}
80658c86148SMariusz Zaborskinvlist_destroy(nvl);
80758c86148SMariusz Zaborski.Ed
80858c86148SMariusz Zaborski.Pp
80958c86148SMariusz ZaborskiReceiving nvlist and getting data:
81058c86148SMariusz Zaborski.Bd -literal
81158c86148SMariusz Zaborskinvlist_t *nvl;
81258c86148SMariusz Zaborskiconst char *command;
81358c86148SMariusz Zaborskichar *filename;
81458c86148SMariusz Zaborskiint fd;
81558c86148SMariusz Zaborski
81658c86148SMariusz Zaborskinvl = nvlist_recv(sock, 0);
81758c86148SMariusz Zaborskiif (nvl == NULL)
81858c86148SMariusz Zaborski	err(1, "nvlist_recv() failed");
81958c86148SMariusz Zaborski
82058c86148SMariusz Zaborski/* For command we take pointer to nvlist's buffer. */
82158c86148SMariusz Zaborskicommand = nvlist_get_string(nvl, "command");
82258c86148SMariusz Zaborski/*
82358c86148SMariusz Zaborski * For filename we remove it from the nvlist and take
82458c86148SMariusz Zaborski * ownership of the buffer.
82558c86148SMariusz Zaborski */
82658c86148SMariusz Zaborskifilename = nvlist_take_string(nvl, "filename");
82758c86148SMariusz Zaborski/* The same for the descriptor. */
82858c86148SMariusz Zaborskifd = nvlist_take_descriptor(nvl, "fd");
82958c86148SMariusz Zaborski
83058c86148SMariusz Zaborskiprintf("command=%s filename=%s fd=%d\n", command, filename, fd);
83158c86148SMariusz Zaborski
83258c86148SMariusz Zaborskinvlist_destroy(nvl);
83358c86148SMariusz Zaborskifree(filename);
83458c86148SMariusz Zaborskiclose(fd);
83558c86148SMariusz Zaborski/* command was freed by nvlist_destroy() */
83658c86148SMariusz Zaborski.Ed
83758c86148SMariusz Zaborski.Pp
83858c86148SMariusz ZaborskiIterating over nvlist:
83958c86148SMariusz Zaborski.Bd -literal
84058c86148SMariusz Zaborskinvlist_t *nvl;
84158c86148SMariusz Zaborskiconst char *name;
84258c86148SMariusz Zaborskivoid *cookie;
84358c86148SMariusz Zaborskiint type;
84458c86148SMariusz Zaborski
84558c86148SMariusz Zaborskinvl = nvlist_recv(sock, 0);
84658c86148SMariusz Zaborskiif (nvl == NULL)
84758c86148SMariusz Zaborski	err(1, "nvlist_recv() failed");
84858c86148SMariusz Zaborski
84958c86148SMariusz Zaborskicookie = NULL;
85058c86148SMariusz Zaborskiwhile ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
85158c86148SMariusz Zaborski	printf("%s=", name);
85258c86148SMariusz Zaborski	switch (type) {
85358c86148SMariusz Zaborski	case NV_TYPE_NUMBER:
85458c86148SMariusz Zaborski		printf("%ju", (uintmax_t)nvlist_get_number(nvl, name));
85558c86148SMariusz Zaborski		break;
85658c86148SMariusz Zaborski	case NV_TYPE_STRING:
85758c86148SMariusz Zaborski		printf("%s", nvlist_get_string(nvl, name));
85858c86148SMariusz Zaborski		break;
85958c86148SMariusz Zaborski	default:
86058c86148SMariusz Zaborski		printf("N/A");
86158c86148SMariusz Zaborski		break;
86258c86148SMariusz Zaborski	}
86358c86148SMariusz Zaborski	printf("\\n");
86458c86148SMariusz Zaborski}
86558c86148SMariusz Zaborski.Ed
86658c86148SMariusz Zaborski.Pp
86758c86148SMariusz ZaborskiIterating over every nested nvlist:
86858c86148SMariusz Zaborski.Bd -literal
86958c86148SMariusz Zaborskinvlist_t *nvl;
87058c86148SMariusz Zaborskiconst char *name;
87158c86148SMariusz Zaborskivoid *cookie;
87258c86148SMariusz Zaborskiint type;
87358c86148SMariusz Zaborski
87458c86148SMariusz Zaborskinvl = nvlist_recv(sock, 0);
87558c86148SMariusz Zaborskiif (nvl == NULL)
87658c86148SMariusz Zaborski	err(1, "nvlist_recv() failed");
87758c86148SMariusz Zaborski
87858c86148SMariusz Zaborskicookie = NULL;
87958c86148SMariusz Zaborskido {
88058c86148SMariusz Zaborski	while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
88158c86148SMariusz Zaborski		if (type == NV_TYPE_NVLIST) {
88258c86148SMariusz Zaborski			nvl = nvlist_get_nvlist(nvl, name);
88358c86148SMariusz Zaborski			cookie = NULL;
88458c86148SMariusz Zaborski		}
88558c86148SMariusz Zaborski	}
88658c86148SMariusz Zaborski} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
88758c86148SMariusz Zaborski.Ed
888347a39b4SMariusz Zaborski.Pp
889347a39b4SMariusz ZaborskiIterating over every nested nvlist and every nvlist element:
890347a39b4SMariusz Zaborski.Bd -literal
891347a39b4SMariusz Zaborskinvlist_t *nvl;
892347a39b4SMariusz Zaborskiconst nvlist_t * const *array;
893347a39b4SMariusz Zaborskiconst char *name;
894347a39b4SMariusz Zaborskivoid *cookie;
895347a39b4SMariusz Zaborskiint type;
896347a39b4SMariusz Zaborski
897347a39b4SMariusz Zaborskinvl = nvlist_recv(sock, 0);
898347a39b4SMariusz Zaborskiif (nvl == null)
899347a39b4SMariusz Zaborski	err(1, "nvlist_recv() failed");
900347a39b4SMariusz Zaborski
901347a39b4SMariusz Zaborskicookie = null;
902347a39b4SMariusz Zaborskido {
903347a39b4SMariusz Zaborski	while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
904347a39b4SMariusz Zaborski		if (type == NV_TYPE_NVLIST) {
905347a39b4SMariusz Zaborski			nvl = nvlist_get_nvlist(nvl, name);
906347a39b4SMariusz Zaborski			cookie = NULL;
907347a39b4SMariusz Zaborski		} else if (type == NV_TYPE_NVLIST_ARRAY) {
908347a39b4SMariusz Zaborski			nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0];
909347a39b4SMariusz Zaborski			cookie = NULL;
910347a39b4SMariusz Zaborski		}
911347a39b4SMariusz Zaborski	}
912347a39b4SMariusz Zaborski} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL);
913347a39b4SMariusz Zaborski.Ed
914347a39b4SMariusz Zaborski.Pp
915347a39b4SMariusz ZaborskiOr alternatively:
916347a39b4SMariusz Zaborski.Bd -literal
917347a39b4SMariusz Zaborskinvlist_t *nvl, *tmp;
918347a39b4SMariusz Zaborskiconst nvlist_t * const *array;
919347a39b4SMariusz Zaborskiconst char *name;
920347a39b4SMariusz Zaborskivoid *cookie;
921347a39b4SMariusz Zaborskiint type;
922347a39b4SMariusz Zaborski
923347a39b4SMariusz Zaborskinvl = nvlist_recv(sock, 0);
924347a39b4SMariusz Zaborskiif (nvl == null)
925347a39b4SMariusz Zaborski	err(1, "nvlist_recv() failed");
926347a39b4SMariusz Zaborski
927347a39b4SMariusz Zaborskicooke = NULL;
928347a39b4SMariusz Zaborskitmp = nvl;
929347a39b4SMariusz Zaborskido {
930347a39b4SMariusz Zaborski	do {
931347a39b4SMariusz Zaborski		nvl = tmp;
932347a39b4SMariusz Zaborski		while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
933347a39b4SMariusz Zaborski			if (type == NV_TYPE_NVLIST) {
934*14ba7925SPawel Jakub Dawidek				nvl = nvlist_get_nvlist(nvl, name);
935347a39b4SMariusz Zaborski				cookie = NULL;
936347a39b4SMariusz Zaborski			} else if (type == NV_TYPE_NVLIST_ARRAY) {
937347a39b4SMariusz Zaborski				nvl = nvlist_get_nvlist_array(nvl, name,
938347a39b4SMariusz Zaborski				    NULL)[0];
939347a39b4SMariusz Zaborski				cookie = NULL;
940347a39b4SMariusz Zaborski			}
941347a39b4SMariusz Zaborski		}
942347a39b4SMariusz Zaborski		cookie = NULL;
943347a39b4SMariusz Zaborski	} while ((tmp = nvlist_get_array_next(nvl)) != NULL);
944347a39b4SMariusz Zaborski} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL);
945347a39b4SMariusz Zaborski.Ed
94658c86148SMariusz Zaborski.Sh SEE ALSO
94758c86148SMariusz Zaborski.Xr close 2 ,
94858c86148SMariusz Zaborski.Xr dup 2 ,
94958c86148SMariusz Zaborski.Xr open 2 ,
95058c86148SMariusz Zaborski.Xr err 3 ,
95158c86148SMariusz Zaborski.Xr free 3 ,
95258c86148SMariusz Zaborski.Xr printf 3 ,
95358c86148SMariusz Zaborski.Xr unix 4
95458c86148SMariusz Zaborski.Sh HISTORY
95558c86148SMariusz ZaborskiThe
95658c86148SMariusz Zaborski.Nm libnv
95758c86148SMariusz Zaborskilibrary appeared in
95858c86148SMariusz Zaborski.Fx 11.0 .
95958c86148SMariusz Zaborski.Sh AUTHORS
96058c86148SMariusz Zaborski.An -nosplit
96158c86148SMariusz ZaborskiThe
96258c86148SMariusz Zaborski.Nm libnv
96358c86148SMariusz Zaborskilibrary was implemented by
96458c86148SMariusz Zaborski.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
96558c86148SMariusz Zaborskiunder sponsorship from the FreeBSD Foundation.
966