Index: share/man/man9/cnv.9 =================================================================== --- share/man/man9/cnv.9 +++ /dev/null @@ -1,200 +0,0 @@ -.\" -.\" 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 26, 2016 -.Dt CNV 9 -.Os -.Sh NAME -.Nm cnvlist_get, -.Nm cnvlist_take, -.Nm cnvlist_free, -.Nd "API for managing name/value pairs by cookie." -.Sh LIBRARY -.Lb libnv -.Sh SYNOPSIS -.In sys/cnv.h -.Ft bool -.Fn cnvlist_get_bool "void *cookiep" -.Ft uint64_t -.Fn cnvlist_get_number "void *cookiep" -.Ft "const char *" -.Fn cnvlist_get_string "void *cookiep" -.Ft "const nvlist_t *" -.Fn cnvlist_get_nvlist "void *cookiep" -.Ft "const void *" -.Fn cnvlist_get_binary "void *cookiep" "size_t *sizep" -.Ft "const bool *" -.Fn cnvlist_get_bool_array "void *cookiep" "size_t *nitemsp" -.Ft "const uint64_t *" -.Fn cnvlist_get_number_array "void *cookiep" "size_t *nitemsp" -.Ft "const char * const *" -.Fn cnvlist_get_string_array "void *cookiep" "size_t *nitemsp" -.Ft "const nvlist_t * const *" -.Fn cnvlist_get_nvlist_array "void *cookiep" "size_t *nitemsp" -.Ft int -.Fn cnvlist_get_descriptor "void *cookiep" -.Ft "const int *" -.Fn cnvlist_get_descriptor_array "void *cookiep" "size_t *nitemsp" -.\" -.Ft bool -.Fn cnvlist_take_bool "void *cookiep" -.Ft uint64_t -.Fn cnvlist_take_number "void *cookiep" -.Ft "const char *" -.Fn cnvlist_take_string "void *cookiep" -.Ft "const nvlist_t *" -.Fn cnvlist_take_nvlist "void *cookiep" -.Ft "const void *" -.Fn cnvlist_take_binary "void *cookiep" "size_t *sizep" -.Ft "const bool *" -.Fn cnvlist_take_bool_array "void *cookiep" "size_t *nitemsp" -.Ft "const uint64_t *" -.Fn cnvlist_take_number_array "void *cookiep" "size_t *nitemsp" -.Ft "const char * const *" -.Fn cnvlist_take_string_array "void *cookiep" "size_t *nitemsp" -.Ft "const nvlist_t * const *" -.Fn cnvlist_take_nvlist_array "void *cookiep" "size_t *nitemsp" -.Ft int -.Fn cnvlist_take_descriptor "void *cookiep" -.Ft "const int *' -.Fn cnvlist_take_descriptor_array "void *cookiep" "size_t *nitemsp" -.\" -.Ft void -.Fn cnvlist_free_null "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_bool "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_number "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_string "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_nvlist "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_descriptor "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_binary "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_bool_array "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_number_array "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_string_array "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_nvlist_array "nvlist_t *nvl" "void *cookiep" -.Ft void -.Fn cnvlist_free_descriptor_array "nvlist_t *nvl" "void *cookiep" -.Sh DESCRIPTION -The -.Nm libnv -library permits easy management of name/value pairs and can send and receive -them over sockets. -For more information, also see -.Xr nv 9 . -.Pp -The concept of cookies is explained in -.Fn nvlist_next , -.Fn nvlist_get_parent , -.Fn nvlist_get_pararr -from -.Xr nv 9 . -.Pp -The -.Nm cnvlist_get -family of functions obtains the value of the supplied cookie. -Returned strings, nvlists, descriptors, binaries, or arrays must not be modified -by the user. -They still belong to the nvlist. -The nvlist must not be in an error state. -.Pp -The -.Nm cnvlist_take -family of functions returns the value associated with the given cookie and -remove the element from the nvlist. -When the value is a string, binary, or array value, the caller is responsible -for freeing returned memory with -.Fn free 3 . -When the value is an nvlist, the caller is responsible for destroying the -returned nvlist with -.Fn nvlist_destroy . -When the value is a descriptor, the caller is responsible for closing the -returned descriptor with the -.Fn close 2 . -.Pp -The -.Nm cnvlist_free -family of functions removes an element of the supplied cookie and frees all -resources. -If an element of the given cookie has the wrong type or does not exist, the -program -is aborted. -.Sh Example -The following example demonstrates how to deal with cnvlist API. -.Bd -literal -int type; -void *cookie, *scookie, *bcookie; -nvlist_t *nvl; -char *name; - -nvl = nvlist_create(0); -nvlist_add_bool(nvl, "test", 1 == 2); -nvlist_add_string(nvl, "test2", "cnvlist"); -cookie = NULL; - -while (nvlist_next(nvl, &type, &cookie) != NULL) { - switch(type) { - case NV_TYPE_BOOL: - printf("test: %d\\n", cnvlist_get_bool(cookie)); - bcookie = cookie; - break; - case NV_TYPE_STRING: - printf("test2: %s\\n", cnvlist_get_string(cookie)); - scookie = cookie; - break; - } -} - -name = cnvlist_take_string(nvl, scookie); -cnvlist_free_bool(nvl, bcookie); - -printf("test2: %s\\n", name); -free(name); - -printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); -nvlist_destroy(nvl); - -return (0); -.Ed -.Sh SEE ALSO -.Xr nv 9 , -.Xr close 2 , -.Xr free 3 -.Sh AUTHORS -.An -nosplit -The -.Nm cnv -API was created during the Google Summer Of Code 2016 by -.An Adam Starak Aq starak.adam@gmail.com