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