share/man/man9/dnv.9

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