From owner-svn-src-all@freebsd.org Wed Oct 5 19:01:02 2016 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 4480DAF6BC5; Wed, 5 Oct 2016 19:01:02 +0000 (UTC) (envelope-from oshogbo@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 07FD69AD; Wed, 5 Oct 2016 19:01:01 +0000 (UTC) (envelope-from oshogbo@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u95J1162061126; Wed, 5 Oct 2016 19:01:01 GMT (envelope-from oshogbo@FreeBSD.org) Received: (from oshogbo@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u95J11tF061125; Wed, 5 Oct 2016 19:01:01 GMT (envelope-from oshogbo@FreeBSD.org) Message-Id: <201610051901.u95J11tF061125@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: oshogbo set sender to oshogbo@FreeBSD.org using -f From: Mariusz Zaborski Date: Wed, 5 Oct 2016 19:01:01 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r306716 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 05 Oct 2016 19:01:02 -0000 Author: oshogbo Date: Wed Oct 5 19:01:00 2016 New Revision: 306716 URL: https://svnweb.freebsd.org/changeset/base/306716 Log: Add man page for dnvlist. Submitted by: Adam Starak Reviewed by: cem, wblock Added: head/share/man/man9/dnv.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Wed Oct 5 18:38:38 2016 (r306715) +++ head/share/man/man9/Makefile Wed Oct 5 19:01:00 2016 (r306716) @@ -114,6 +114,7 @@ MAN= accept_filter.9 \ devstat.9 \ devtoname.9 \ disk.9 \ + dnv.9 \ domain.9 \ drbr.9 \ driver.9 \ @@ -761,6 +762,19 @@ MLINKS+=disk.9 disk_alloc.9 \ 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 \ Added: head/share/man/man9/dnv.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/dnv.9 Wed Oct 5 19:01:00 2016 (r306716) @@ -0,0 +1,116 @@ +.\" +.\" 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 DNV 9 +.Os +.Sh NAME +.Nm dnvlist_get, +.Nm dnvlist_take, +.Nd "API for getting name/value pairs. Nonexistent pairs do not raise an error." +.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 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 +.Nm dnvlist_get +family of functions returns the value associated with the specified name. +If an element of the specified name does not exist, the function returns the +value provided in +.Fa defval . +Returned strings, nvlists, descriptors, binaries, or arrays must not be modified +by the user. +They still belong to the nvlist. +If the nvlist is in an error state, attempts to use any of these functions will +cause the program to abort. +.Pp +The +.Nm dnvlist_take +family of functions returns the value associated with the specified name and +removes the element from the nvlist. +If an element of the supplied name does not exist, the value provided in +.Nm defval +is returned. +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 +.Fn close 2 . +.Sh SEE ALSO +.Xr close 2 , +.Xr free 3 , +.Xr nv 9 +.Sh HISTORY +The +.Nm dnv +API appeared in +.Fx 11.0 . +.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. +This manual page was written by +.An Adam Starak Aq Mt starak.adam@gmail.com