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