1.\" 2.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd January 3, 2025 27.Dt DNV 9 28.Os 29.Sh NAME 30.Nm dnvlist_get , 31.Nm dnvlist_take 32.Nd "API for getting name/value pairs with a default value" 33.Sh LIBRARY 34.Lb libnv 35.Sh SYNOPSIS 36.In sys/dnv.h 37.Ft bool 38.Fn dnvlist_get_bool "const nvlist_t *nvl" "const char *name" "bool defval" 39.Ft uint64_t 40.Fn dnvlist_get_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" 41.Ft char * 42.Fn dnvlist_get_string "const nvlist_t *nvl" "const char *name" "const char *defval" 43.Ft nvlist_t * 44.Fn dnvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" 45.Ft int 46.Fn dnvlist_get_descriptor "const nvlist_t *nvl" "const char *name" "int defval" 47.Ft void * 48.Fn dnvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" 49.Ft bool 50.Fn dnvlist_take_bool "const nvlist_t *nvl" "const char *name" "bool defval" 51.Ft uint64_t 52.Fn dnvlist_take_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" 53.Ft char * 54.Fn dnvlist_take_string "const nvlist_t *nvl" "const char *name" "const char *defval" 55.Ft nvlist_t * 56.Fn dnvlist_take_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" 57.Ft int 58.Fn dnvlist_take_descriptor "const nvlist_t *nvl" "const char *name" "int defval" 59.Ft void * 60.Fn dnvlist_take_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" 61.Sh DESCRIPTION 62The 63.Nm libnv 64library permits easy management of name/value pairs and can send and receive 65them over sockets. 66For more information, see 67.Xr nv 9 . 68.Pp 69The 70.Nm dnvlist_get 71functions return the value associated with 72.Fa name . 73If an element named 74.Fa name 75does not exist, the function returns the 76value provided in 77.Fa defval . 78Returned strings, nvlists, descriptors, binaries, or arrays must not be modified 79by the user since they still belong to the nvlist. 80If the nvlist is in an error state, attempts to use any of these functions will 81cause the program to abort. 82.Pp 83The 84.Nm dnvlist_take 85functions return the value associated with 86.Fa name 87and removes the associated element from 88.Fa nvl . 89If an element named 90.Fa name 91does not exist, the value provided in 92.Nm defval 93is returned. 94When the value is a string, binary, or array value, the caller is 95responsible for freeing returned memory with 96.Fn free 3 . 97When the value is an nvlist, the caller is responsible for destroying the 98returned nvlist with 99.Fn nvlist_destroy . 100When the value is a descriptor, the caller is responsible for closing the 101returned descriptor with 102.Fn close 2 . 103.Sh SEE ALSO 104.Xr close 2 , 105.Xr free 3 , 106.Xr nv 9 107.Sh HISTORY 108The 109.Nm dnv 110API appeared in 111.Fx 11.0 . 112.Sh AUTHORS 113.An -nosplit 114The 115.Nm dnv 116API was implemented by 117.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 118under sponsorship from the FreeBSD Foundation. 119This manual page was written by 120.An Adam Starak Aq Mt starak.adam@gmail.com 121