Index: share/man/man9/Makefile =================================================================== --- share/man/man9/Makefile +++ share/man/man9/Makefile @@ -113,6 +113,7 @@ devstat.9 \ devtoname.9 \ disk.9 \ + dnv.9 \ domain.9 \ drbr.9 \ driver.9 \ @@ -724,6 +725,19 @@ disk.9 disk_destroy.9 \ disk.9 disk_gone.9 \ disk.9 disk_resize.9 +MLINKS+=dnv.9 dnvlist.9 \ + dnv.9 dnvlist_get_binary.9 \ + dnv.9 dnvlist_get_bool.9 \ + dnv.9 dnvlist_get_descriptor.9 \ + dnv.9 dnvlist_get_number.9 \ + dnv.9 dnvlist_get_nvlist.9 \ + dnv.9 dnvlist_get_string.9 \ + dnv.9 dnvlist_take_binary.9 \ + dnv.9 dnvlist_take_bool.9 \ + dnv.9 dnvlist_take_descriptor.9 \ + dnv.9 dnvlist_take_number.9 \ + dnv.9 dnvlist_take_nvlist.9 \ + dnv.9 dnvlist_take_string.9 \ MLINKS+=domain.9 DOMAIN_SET.9 \ domain.9 domain_add.9 \ domain.9 pfctlinput.9 \ Index: share/man/man9/dnv.9 =================================================================== --- /dev/null +++ share/man/man9/dnv.9 @@ -0,0 +1,105 @@ +.\" +.\" Copyright (c) 2016 Adam Starak +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 18, 2016 +.Dt DNV 9 +.Os +.Sh NAME +.Nm dnvlist_get, +.Nm dnvlist_take, +.Nd "API for getting name/value pairs, which doesn't raise an error if pair +doesn't exist". +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/dnv.h +.Ft bool +.Fn dnvlist_get_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_get_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_get_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_get_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Ft bool +.Fn dnvlist_take_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_take_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_take_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_take_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_take_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_take_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Sh DESCRIPTION +The +.Nm libnv +library allows to easily manage name value pairs as well as send and receive +them over sockets. For more information see also +.Xr nv 9 . +.Pp +The +.Nm dnvlist_get +family functions returns value associated with the given name. If the element +of given name doesn't exist, the function will return value provided in defval. +In case of string, nvlist, descriptor, binary or any array, returned resource +should not be modified - it still belongs to the nvlist. The nvlist must not be +in error state. +.Pp +The +.Nm dnvlist_take +family functions returns value associated with the given name and remove the +element from the nvlist. If the element of given name doesn't exist, the value +provided in defval. In case of string, binary or any array values, the caller is +responsible for freeing returned memory using the +.Fn free 3 +function. +In case of nvlist, the caller is responsible for destroying returned nvlist +using the +.Fn nvlist_destroy +function. +In case of descriptor, the caller is responsible for closing returned descriptor +using the +.Fn close 2 +system call. +.Sh SEE ALSO +.Xr nv 9 , +.Xr close 2 , +.Xr free 3 +.Sh AUTHORS +.An -nosplit +The +.Nm dnv +API was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation.