Date: Sat, 27 Aug 2016 13:47:52 +0000 (UTC) From: Mariusz Zaborski <oshogbo@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r304910 - head/share/man/man9 Message-ID: <201608271347.u7RDlqIu069425@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: oshogbo Date: Sat Aug 27 13:47:52 2016 New Revision: 304910 URL: https://svnweb.freebsd.org/changeset/base/304910 Log: Introduce cnv man page. Submitted by: Adam Starak <starak.adam@gmail.com> Reviewed by: cem@, wblock@ Differential Revision: https://reviews.freebsd.org/D7249 Added: head/share/man/man9/cnv.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sat Aug 27 13:40:27 2016 (r304909) +++ head/share/man/man9/Makefile Sat Aug 27 13:47:52 2016 (r304910) @@ -57,6 +57,7 @@ MAN= accept_filter.9 \ byteorder.9 \ casuword.9 \ cd.9 \ + cnv.9 \ condvar.9 \ config_intrhook.9 \ contigmalloc.9 \ @@ -617,6 +618,41 @@ MLINKS+=byteorder.9 be16dec.9 \ byteorder.9 le64dec.9 \ byteorder.9 le64enc.9 \ byteorder.9 le64toh.9 +MLINKS+=cnv.9 cnvlist.9 \ + cnv.9 cnvlist_free_binary.9 \ + cnv.9 cnvlist_free_bool.9 \ + cnv.9 cnvlist_free_bool_array.9 \ + cnv.9 cnvlist_free_descriptor.9 \ + cnv.9 cnvlist_free_descriptor_array.9 \ + cnv.9 cnvlist_free_null.9 \ + cnv.9 cnvlist_free_number.9 \ + cnv.9 cnvlist_free_number_array.9 \ + cnv.9 cnvlist_free_nvlist.9 \ + cnv.9 cnvlist_free_nvlist_array.9 \ + cnv.9 cnvlist_free_string.9 \ + cnv.9 cnvlist_free_string_array.9 \ + cnv.9 cnvlist_get_binary.9 \ + cnv.9 cnvlist_get_bool.9 \ + cnv.9 cnvlist_get_bool_array.9 \ + cnv.9 cnvlist_get_descriptor.9 \ + cnv.9 cnvlist_get_descriptor_array.9 \ + cnv.9 cnvlist_get_number.9 \ + cnv.9 cnvlist_get_number_array.9 \ + cnv.9 cnvlist_get_nvlist.9 \ + cnv.9 cnvlist_get_nvlist_array.9 \ + cnv.9 cnvlist_get_string.9 \ + cnv.9 cnvlist_get_string_array.9 \ + cnv.9 cnvlist_take_binary.9 \ + cnv.9 cnvlist_take_bool.9 \ + cnv.9 cnvlist_take_bool_array.9 \ + cnv.9 cnvlist_take_descriptor.9 \ + cnv.9 cnvlist_take_descriptor_array.9 \ + cnv.9 cnvlist_take_number.9 \ + cnv.9 cnvlist_take_number_array.9 \ + cnv.9 cnvlist_take_nvlist.9 \ + cnv.9 cnvlist_take_nvlist_array.9 \ + cnv.9 cnvlist_take_string.9 \ + cnv.9 cnvlist_take_string_array.9 MLINKS+=condvar.9 cv_broadcast.9 \ condvar.9 cv_broadcastpri.9 \ condvar.9 cv_destroy.9 \ Added: head/share/man/man9/cnv.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/cnv.9 Sat Aug 27 13:47:52 2016 (r304910) @@ -0,0 +1,199 @@ +.\" +.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com> +.\" 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 , +and +.Fn nvlist_get_pararr +from +.Xr nv 9 . +.Pp +The +.Nm cnvlist_get +family of functions obtains the value associated with the given cookie. +Returned strings, nvlists, descriptors, binaries, or arrays must not be modified +by the user, since 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 +removes the element from the nvlist. +When the value is a string, binary, or array value, the caller is responsible +for freeing the 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201608271347.u7RDlqIu069425>