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 July 26, 2016 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. Nonexistent pairs do not raise an error." 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, also see 67.Xr nv 9 . 68.Pp 69The 70.Nm dnvlist_get 71family of functions returns the value associated with the specified name. 72If an element of the specified name does not exist, the function returns the 73value provided in 74.Fa defval . 75Returned strings, nvlists, descriptors, binaries, or arrays must not be modified 76by the user. 77They still belong to the nvlist. 78If the nvlist is in an error state, attempts to use any of these functions will 79cause the program to abort. 80.Pp 81The 82.Nm dnvlist_take 83family of functions returns the value associated with the specified name and 84removes the element from the nvlist. 85If an element of the supplied name does not exist, the value provided in 86.Nm defval 87is returned. 88When the value is a string, binary, or array value, the caller is 89responsible for freeing returned memory with 90.Fn free 3 . 91When the value is an nvlist, the caller is responsible for destroying the 92returned nvlist with 93.Fn nvlist_destroy . 94When the value is a descriptor, the caller is responsible for closing the 95returned descriptor with 96.Fn close 2 . 97.Sh SEE ALSO 98.Xr close 2 , 99.Xr free 3 , 100.Xr nv 9 101.Sh HISTORY 102The 103.Nm dnv 104API appeared in 105.Fx 11.0 . 106.Sh AUTHORS 107.An -nosplit 108The 109.Nm dnv 110API was implemented by 111.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 112under sponsorship from the FreeBSD Foundation. 113This manual page was written by 114.An Adam Starak Aq Mt starak.adam@gmail.com 115