share/man/man9/cnv.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 August 27, 2016
  29 .Dt CNV 9
  30 .Os
  31 .Sh NAME
  32 .Nm cnvlist_get,
  33 .Nm cnvlist_take,
  34 .Nm cnvlist_free,
  35 .Nd "API for managing name/value pairs by cookie."
  36 .Sh LIBRARY
  37 .Lb libnv
  38 .Sh SYNOPSIS
  39 .In sys/cnv.h
  40 .Ft bool
  41 .Fn cnvlist_get_bool "void *cookiep"
  42 .Ft uint64_t
  43 .Fn cnvlist_get_number "void *cookiep"
  44 .Ft "const char *"
  45 .Fn cnvlist_get_string "void *cookiep"
  46 .Ft "const nvlist_t *"
  47 .Fn cnvlist_get_nvlist "void *cookiep"
  48 .Ft "const void *"
  49 .Fn cnvlist_get_binary "void *cookiep" "size_t *sizep"
  50 .Ft "const bool *"
  51 .Fn cnvlist_get_bool_array "void *cookiep" "size_t *nitemsp"
  52 .Ft "const uint64_t *"
  53 .Fn cnvlist_get_number_array "void *cookiep" "size_t *nitemsp"
  54 .Ft "const char * const *"
  55 .Fn cnvlist_get_string_array "void *cookiep" "size_t *nitemsp"
  56 .Ft "const nvlist_t * const *"
  57 .Fn cnvlist_get_nvlist_array "void *cookiep" "size_t *nitemsp"
  58 .Ft int
  59 .Fn cnvlist_get_descriptor "void *cookiep"
  60 .Ft "const int *"
  61 .Fn cnvlist_get_descriptor_array "void *cookiep" "size_t *nitemsp"
  62 .\"
  63 .Ft bool
  64 .Fn cnvlist_take_bool "void *cookiep"
  65 .Ft uint64_t
  66 .Fn cnvlist_take_number "void *cookiep"
  67 .Ft "const char *"
  68 .Fn cnvlist_take_string "void *cookiep"
  69 .Ft "const nvlist_t *"
  70 .Fn cnvlist_take_nvlist "void *cookiep"
  71 .Ft "const void *"
  72 .Fn cnvlist_take_binary "void *cookiep" "size_t *sizep"
  73 .Ft "const bool *"
  74 .Fn cnvlist_take_bool_array "void *cookiep" "size_t *nitemsp"
  75 .Ft "const uint64_t *"
  76 .Fn cnvlist_take_number_array "void *cookiep" "size_t *nitemsp"
  77 .Ft "const char * const *"
  78 .Fn cnvlist_take_string_array "void *cookiep" "size_t *nitemsp"
  79 .Ft "const nvlist_t * const *"
  80 .Fn cnvlist_take_nvlist_array "void *cookiep" "size_t *nitemsp"
  81 .Ft int
  82 .Fn cnvlist_take_descriptor "void *cookiep"
  83 .Ft "const int *"
  84 .Fn cnvlist_take_descriptor_array "void *cookiep" "size_t *nitemsp"
  85 .\"
  86 .Ft void
  87 .Fn cnvlist_free_null "nvlist_t *nvl" "void *cookiep"
  88 .Ft void
  89 .Fn cnvlist_free_bool "nvlist_t *nvl" "void *cookiep"
  90 .Ft void
  91 .Fn cnvlist_free_number "nvlist_t *nvl" "void *cookiep"
  92 .Ft void
  93 .Fn cnvlist_free_string "nvlist_t *nvl" "void *cookiep"
  94 .Ft void
  95 .Fn cnvlist_free_nvlist "nvlist_t *nvl" "void *cookiep"
  96 .Ft void
  97 .Fn cnvlist_free_descriptor "nvlist_t *nvl" "void *cookiep"
  98 .Ft void
  99 .Fn cnvlist_free_binary "nvlist_t *nvl" "void *cookiep"
 100 .Ft void
 101 .Fn cnvlist_free_bool_array "nvlist_t *nvl" "void *cookiep"
 102 .Ft void
 103 .Fn cnvlist_free_number_array "nvlist_t *nvl" "void *cookiep"
 104 .Ft void
 105 .Fn cnvlist_free_string_array "nvlist_t *nvl" "void *cookiep"
 106 .Ft void
 107 .Fn cnvlist_free_nvlist_array "nvlist_t *nvl" "void *cookiep"
 108 .Ft void
 109 .Fn cnvlist_free_descriptor_array "nvlist_t *nvl" "void *cookiep"
 110 .Sh DESCRIPTION
 111 The
 112 .Nm libnv
 113 library permits easy management of name/value pairs and can send and receive
 114 them over sockets.
 115 For more information, also see
 116 .Xr nv 9 .
 117 .Pp
 118 The concept of cookies is explained in
 119 .Fn nvlist_next ,
 120 .Fn nvlist_get_parent ,
 121 and
 122 .Fn nvlist_get_pararr
 123 from
 124 .Xr nv 9 .
 125 .Pp
 126 The
 127 .Nm cnvlist_get
 128 family of functions obtains the value associated with the given cookie.
 129 Returned strings, nvlists, descriptors, binaries, or arrays must not be modified
 130 by the user, since they still belong to the nvlist.
 131 The nvlist must not be in an error state.
 132 .Pp
 133 The
 134 .Nm cnvlist_take
 135 family of functions returns the value associated with the given cookie and
 136 removes the element from the nvlist.
 137 When the value is a string, binary, or array value, the caller is responsible
 138 for freeing the returned memory with
 139 .Fn free 3 .
 140 When the value is an nvlist, the caller is responsible for destroying the
 141 returned nvlist with
 142 .Fn nvlist_destroy .
 143 When the value is a descriptor, the caller is responsible for closing the
 144 returned descriptor with the
 145 .Fn close 2 .
 146 .Pp
 147 The
 148 .Nm cnvlist_free
 149 family of functions removes an element of the supplied cookie and frees all
 150 resources.
 151 If an element of the given cookie has the wrong type or does not exist, the
 152 program
 153 is aborted.
 154 .Sh EXAMPLE
 155 The following example demonstrates how to deal with cnvlist API.
 156 .Bd -literal
 157 int type;
 158 void *cookie, *scookie, *bcookie;
 159 nvlist_t *nvl;
 160 char *name;
 161
 162 nvl = nvlist_create(0);
 163 nvlist_add_bool(nvl, "test", 1 == 2);
 164 nvlist_add_string(nvl, "test2", "cnvlist");
 165 cookie = NULL;
 166
 167 while (nvlist_next(nvl, &type, &cookie) != NULL) {
 168         switch (type) {
 169         case NV_TYPE_BOOL:
 170                 printf("test: %d\\n", cnvlist_get_bool(cookie));
 171                 bcookie = cookie;
 172                 break;
 173         case NV_TYPE_STRING:
 174                 printf("test2: %s\\n", cnvlist_get_string(cookie));
 175                 scookie = cookie;
 176                 break;
 177         }
 178 }
 179
 180 name = cnvlist_take_string(nvl, scookie);
 181 cnvlist_free_bool(nvl, bcookie);
 182
 183 printf("test2: %s\\n", name);
 184 free(name);
 185
 186 printf("nvlist_empty = %d\\n", nvlist_empty(nvl));
 187 nvlist_destroy(nvl);
 188
 189 return (0);
 190 .Ed
 191 .Sh SEE ALSO
 192 .Xr close 2 ,
 193 .Xr free 3 ,
 194 .Xr nv 9
 195 .Sh AUTHORS
 196 The
 197 .Nm cnv
 198 API was created during the Google Summer Of Code 2016 by
 199 .An Adam Starak .