share/man/man9/nv.9

   1 .\"
   2 .\" Copyright (c) 2013 The FreeBSD Foundation
   3 .\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   7 .\" the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd September 16, 2017
  33 .Dt NV 9
  34 .Os
  35 .Sh NAME
  36 .Nm nvlist_create ,
  37 .Nm nvlist_destroy ,
  38 .Nm nvlist_error ,
  39 .Nm nvlist_set_error ,
  40 .Nm nvlist_empty ,
  41 .Nm nvlist_flags ,
  42 .Nm nvlist_exists ,
  43 .Nm nvlist_free ,
  44 .Nm nvlist_clone ,
  45 .Nm nvlist_dump ,
  46 .Nm nvlist_fdump ,
  47 .Nm nvlist_size ,
  48 .Nm nvlist_pack ,
  49 .Nm nvlist_unpack ,
  50 .Nm nvlist_send ,
  51 .Nm nvlist_recv ,
  52 .Nm nvlist_xfer ,
  53 .Nm nvlist_in_array ,
  54 .Nm nvlist_next ,
  55 .Nm nvlist_add ,
  56 .Nm nvlist_move ,
  57 .Nm nvlist_get ,
  58 .Nm nvlist_take
  59 .Nd "library for name/value pairs"
  60 .Sh LIBRARY
  61 .Lb libnv
  62 .Sh SYNOPSIS
  63 .In sys/nv.h
  64 .Ft "nvlist_t *"
  65 .Fn nvlist_create "int flags"
  66 .Ft void
  67 .Fn nvlist_destroy "nvlist_t *nvl"
  68 .Ft int
  69 .Fn nvlist_error "const nvlist_t *nvl"
  70 .Ft void
  71 .Fn nvlist_set_error "nvlist_t *nvl" "int error"
  72 .Ft bool
  73 .Fn nvlist_empty "const nvlist_t *nvl"
  74 .Ft int
  75 .Fn nvlist_flags "const nvlist_t *nvl"
  76 .Ft bool
  77 .Fn nvlist_in_array "const nvlist_t *nvl"
  78 .\"
  79 .Ft "nvlist_t *"
  80 .Fn nvlist_clone "const nvlist_t *nvl"
  81 .\"
  82 .Ft void
  83 .Fn nvlist_dump "const nvlist_t *nvl" "int fd"
  84 .Ft void
  85 .Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp"
  86 .\"
  87 .Ft size_t
  88 .Fn nvlist_size "const nvlist_t *nvl"
  89 .Ft "void *"
  90 .Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep"
  91 .Ft "nvlist_t *"
  92 .Fn nvlist_unpack "const void *buf" "size_t size" "int flags"
  93 .\"
  94 .Ft int
  95 .Fn nvlist_send "int sock" "const nvlist_t *nvl"
  96 .Ft "nvlist_t *"
  97 .Fn nvlist_recv "int sock" "int flags"
  98 .Ft "nvlist_t *"
  99 .Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags"
 100 .\"
 101 .Ft "const char *"
 102 .Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep"
 103 .\"
 104 .Ft bool
 105 .Fn nvlist_exists "const nvlist_t *nvl" "const char *name"
 106 .Ft bool
 107 .Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type"
 108 .Ft bool
 109 .Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name"
 110 .Ft bool
 111 .Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name"
 112 .Ft bool
 113 .Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name"
 114 .Ft bool
 115 .Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name"
 116 .Ft bool
 117 .Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name"
 118 .Ft bool
 119 .Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name"
 120 .Ft bool
 121 .Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name"
 122 .Ft bool
 123 .Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name"
 124 .Ft bool
 125 .Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name"
 126 .Ft bool
 127 .Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name"
 128 .Ft bool
 129 .Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name"
 130 .Ft bool
 131 .Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name"
 132 .\"
 133 .Ft void
 134 .Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
 135 .Ft void
 136 .Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value"
 137 .Ft void
 138 .Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value"
 139 .Ft void
 140 .Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value"
 141 .Ft void
 142 .Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..."
 143 .Ft void
 144 .Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap"
 145 .Ft void
 146 .Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value"
 147 .Ft void
 148 .Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value"
 149 .Ft void
 150 .Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size"
 151 .Ft void
 152 .Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems"
 153 .
 154 .Ft void
 155 .Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems"
 156 .
 157 .Ft void
 158 .Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems"
 159 .
 160 .Ft void
 161 .Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems"
 162 .
 163 .Ft void
 164 .Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems"
 165 .\"
 166 .Ft void
 167 .Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
 168 .Ft void
 169 .Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value"
 170 .Ft void
 171 .Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value"
 172 .Ft void
 173 .Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size"
 174 .Ft void
 175 .Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems"
 176 .
 177 .Ft void
 178 .Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems"
 179 .
 180 .Ft void
 181 .Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems"
 182 .
 183 .Ft void
 184 .Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems"
 185 .
 186 .Ft void
 187 .Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems"
 188 .\"
 189 .Ft bool
 190 .Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
 191 .Ft uint64_t
 192 .Fn nvlist_get_number "const nvlist_t *nvl" "const char *name"
 193 .Ft "const char *"
 194 .Fn nvlist_get_string "const nvlist_t *nvl" "const char *name"
 195 .Ft "const nvlist_t *"
 196 .Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name"
 197 .Ft int
 198 .Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name"
 199 .Ft "const void *"
 200 .Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep"
 201 .Ft "const bool *"
 202 .Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 203 .Ft "const uint64_t *"
 204 .Fn nvlist_get_number_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 205 .Ft "const char * const *"
 206 .Fn nvlist_get_string_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 207 .Ft "const nvlist_t * const *"
 208 .Fn nvlist_get_nvlist_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 209 .Ft "const int *"
 210 .Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 211 .Ft "const nvlist_t *"
 212 .Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
 213 .Ft "const nvlist_t *"
 214 .Fn nvlist_get_array_next "const nvlist_t *nvl"
 215 .Ft "const nvlist_t *"
 216 .Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep"
 217 .\"
 218 .Ft bool
 219 .Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
 220 .Ft uint64_t
 221 .Fn nvlist_take_number "nvlist_t *nvl" "const char *name"
 222 .Ft "char *"
 223 .Fn nvlist_take_string "nvlist_t *nvl" "const char *name"
 224 .Ft "nvlist_t *"
 225 .Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name"
 226 .Ft int
 227 .Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name"
 228 .Ft "void *"
 229 .Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep"
 230 .Ft "bool *"
 231 .Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
 232 .Ft "uint64_t **"
 233 .Fn nvlist_take_number_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
 234 .Ft "char **"
 235 .Fn nvlist_take_string_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
 236 .Ft "nvlist_t **"
 237 .Fn nvlist_take_nvlist_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
 238 .Ft "int *"
 239 .Fn nvlist_take_descriptor_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
 240 .\"
 241 .Ft void
 242 .Fn nvlist_free "nvlist_t *nvl" "const char *name"
 243 .Ft void
 244 .Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type"
 245 .\"
 246 .Ft void
 247 .Fn nvlist_free_null "nvlist_t *nvl" "const char *name"
 248 .Ft void
 249 .Fn nvlist_free_bool "nvlist_t *nvl" "const char *name"
 250 .Ft void
 251 .Fn nvlist_free_number "nvlist_t *nvl" "const char *name"
 252 .Ft void
 253 .Fn nvlist_free_string "nvlist_t *nvl" "const char *name"
 254 .Ft void
 255 .Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name"
 256 .Ft void
 257 .Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
 258 .Ft void
 259 .Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
 260 .Ft void
 261 .Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name"
 262 .Ft void
 263 .Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name"
 264 .Ft void
 265 .Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name"
 266 .Ft void
 267 .Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name"
 268 .Ft void
 269 .Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name"
 270 .Sh DESCRIPTION
 271 The
 272 .Nm libnv
 273 library allows to easily manage name value pairs as well as send and receive
 274 them over sockets.
 275 A group (list) of name value pairs is called an
 276 .Nm nvlist .
 277 The API supports the following data types:
 278 .Bl -ohang -offset indent
 279 .It Sy null ( NV_TYPE_NULL )
 280 There is no data associated with the name.
 281 .It Sy bool ( NV_TYPE_BOOL )
 282 The value can be either
 283 .Dv true
 284 or
 285 .Dv false .
 286 .It Sy number ( NV_TYPE_NUMBER )
 287 The value is a number stored as
 288 .Vt uint64_t .
 289 .It Sy string ( NV_TYPE_STRING )
 290 The value is a C string.
 291 .It Sy nvlist ( NV_TYPE_NVLIST )
 292 The value is a nested nvlist.
 293 .It Sy descriptor ( NV_TYPE_DESCRIPTOR )
 294 The value is a file descriptor.
 295 Note that file descriptors can be sent only over
 296 .Xr unix 4
 297 domain sockets.
 298 .It Sy binary ( NV_TYPE_BINARY )
 299 The value is a binary buffer.
 300 .It Sy bool array ( NV_TYPE_BOOL_ARRAY )
 301 The value is an array of boolean values.
 302 .It Sy number array ( NV_TYPE_NUMBER_ARRAY )
 303 The value is an array of numbers, each stored as
 304 .Vt uint64_t .
 305 .It Sy string array ( NV_TYPE_STRING_ARRAY )
 306 The value is an array of C strings.
 307 .It Sy nvlist array  ( NV_TYPE_NVLIST_ARRAY )
 308 The value is an array of nvlists.
 309 When an nvlist is added to an array, it becomes part of the primary nvlist.
 310 Traversing these arrays can be done using the
 311 .Fn nvlist_get_array_next
 312 and
 313 .Fn nvlist_get_pararr
 314 functions.
 315 .It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY )
 316 The value is an array of files descriptors.
 317 .El
 318 .Pp
 319 The
 320 .Fn nvlist_create
 321 function allocates memory and initializes an nvlist.
 322 .Pp
 323 The following flag can be provided:
 324 .Pp
 325 .Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent
 326 .It Dv NV_FLAG_IGNORE_CASE
 327 Perform case-insensitive lookups of provided names.
 328 .It Dv NV_FLAG_NO_UNIQUE
 329 Names in the nvlist do not have to be unique.
 330 .El
 331 .Pp
 332 The
 333 .Fn nvlist_destroy
 334 function destroys the given nvlist.
 335 Function does nothing if
 336 .Dv NULL
 337 nvlist is provided.
 338 Function never modifies the
 339 .Va errno
 340 global variable.
 341 .Pp
 342 The
 343 .Fn nvlist_error
 344 function returns any error value that the nvlist accumulated.
 345 If the given nvlist is
 346 .Dv NULL
 347 the
 348 .Er ENOMEM
 349 error will be returned.
 350 .Pp
 351 The
 352 .Fn nvlist_set_error
 353 function sets an nvlist to be in the error state.
 354 Subsequent calls to
 355 .Fn nvlist_error
 356 will return the given error value.
 357 This function cannot be used to clear the error state from an nvlist.
 358 This function does nothing if the nvlist is already in the error state.
 359 .Pp
 360 The
 361 .Fn nvlist_empty
 362 function returns
 363 .Dv true
 364 if the given nvlist is empty and
 365 .Dv false
 366 otherwise.
 367 The nvlist must not be in error state.
 368 .Pp
 369 The
 370 .Fn nvlist_flags
 371 function returns flags used to create the nvlist with the
 372 .Fn nvlist_create
 373 function.
 374 .Pp
 375 The
 376 .Fn nvlist_in_array
 377 function returns
 378 .Dv true
 379 if
 380 .Fa nvl
 381 is part of an array that is a member of another nvlist.
 382 .Pp
 383 The
 384 .Fn nvlist_clone
 385 functions clones the given nvlist.
 386 The clone shares no resources with its origin.
 387 This also means that all file descriptors that are part of the nvlist will be
 388 duplicated with the
 389 .Xr dup 2
 390 system call before placing them in the clone.
 391 .Pp
 392 The
 393 .Fn nvlist_dump
 394 dumps nvlist content for debugging purposes to the given file descriptor
 395 .Fa fd .
 396 .Pp
 397 The
 398 .Fn nvlist_fdump
 399 dumps nvlist content for debugging purposes to the given file stream
 400 .Fa fp .
 401 .Pp
 402 The
 403 .Fn nvlist_size
 404 function returns the size of the given nvlist after converting it to binary
 405 buffer with the
 406 .Fn nvlist_pack
 407 function.
 408 .Pp
 409 The
 410 .Fn nvlist_pack
 411 function converts the given nvlist to a binary buffer.
 412 The function allocates memory for the buffer, which should be freed with the
 413 .Xr free 3
 414 function.
 415 If the
 416 .Fa sizep
 417 argument is not
 418 .Dv NULL ,
 419 the size of the buffer will be stored there.
 420 The function returns
 421 .Dv NULL
 422 in case of an error (allocation failure).
 423 If the nvlist contains any file descriptors
 424 .Dv NULL
 425 will be returned.
 426 The nvlist must not be in error state.
 427 .Pp
 428 The
 429 .Fn nvlist_unpack
 430 function converts the given buffer to the nvlist.
 431 The
 432 .Fa flags
 433 argument defines what type of the top level nvlist is expected to be.
 434 Flags are set up using the
 435 .Fn nvlist_create
 436 function.
 437 If the nvlist flags do not match the flags passed to
 438 .Fn nvlist_unpack ,
 439 the nvlist will not be returned.
 440 Every nested nvlist list should be checked using
 441 .Fn nvlist_flags
 442 function.
 443 The function returns
 444 .Dv NULL
 445 in case of an error.
 446 .Pp
 447 The
 448 .Fn nvlist_send
 449 function sends the given nvlist over the socket given by the
 450 .Fa sock
 451 argument.
 452 Note that nvlist that contains file descriptors can only be send over
 453 .Xr unix 4
 454 domain sockets.
 455 .Pp
 456 The
 457 .Fn nvlist_recv
 458 function receives nvlist over the socket given by the
 459 .Fa sock
 460 argument.
 461 The
 462 .Fa flags
 463 argument defines what type of the top level nvlist is expected to be.
 464 Flags are set up using the
 465 .Fn nvlist_create
 466 function.
 467 If the nvlist flags do not match the flags passed to
 468 .Fn nvlist_recv ,
 469 the nvlist will not be returned.
 470 Every nested nvlist list should be checked using
 471 .Fn nvlist_flags
 472 function.
 473 .Pp
 474 The
 475 .Fn nvlist_xfer
 476 function sends the given nvlist over the socket given by the
 477 .Fa sock
 478 argument and receives nvlist over the same socket.
 479 The
 480 .Fa flags
 481 argument defines what type of the top level nvlist is expected to be.
 482 Flags are set up using the
 483 .Fn nvlist_create
 484 function.
 485 If the nvlist flags do not match the flags passed to
 486 .Fn nvlist_xfer ,
 487 the nvlist will not be returned.
 488 Every nested nvlist list should be checked using
 489 .Fn nvlist_flags
 490 function.
 491 The given nvlist is always destroyed.
 492 .Pp
 493 The
 494 .Fn nvlist_next
 495 function iterates over the given nvlist returning names and types of subsequent
 496 elements.
 497 The
 498 .Fa cookiep
 499 argument allows the function to figure out which element should be returned
 500 next.
 501 The
 502 .Va *cookiep
 503 should be set to
 504 .Dv NULL
 505 for the first call and should not be changed later.
 506 Returning
 507 .Dv NULL
 508 means there are no more elements on the nvlist.
 509 The
 510 .Fa typep
 511 argument can be NULL.
 512 Elements may not be removed from the nvlist while traversing it.
 513 The nvlist must not be in error state.
 514 Note that
 515 .Fn nvlist_next
 516 will handle
 517 .Va cookiep
 518 being set to
 519 .Dv NULL .
 520 In this case first element is returned or
 521 .Dv NULL
 522 if nvlist is empty.
 523 This behavior simplifies removing the first element from the list.
 524 .Pp
 525 The
 526 .Fn nvlist_exists
 527 function returns
 528 .Dv true
 529 if element of the given name exists (besides of its type) or
 530 .Dv false
 531 otherwise.
 532 The nvlist must not be in error state.
 533 .Pp
 534 The
 535 .Fn nvlist_exists_type
 536 function returns
 537 .Dv true
 538 if element of the given name and the given type exists or
 539 .Dv false
 540 otherwise.
 541 The nvlist must not be in error state.
 542 .Pp
 543 The
 544 .Fn nvlist_exists_null ,
 545 .Fn nvlist_exists_bool ,
 546 .Fn nvlist_exists_number ,
 547 .Fn nvlist_exists_string ,
 548 .Fn nvlist_exists_nvlist ,
 549 .Fn nvlist_exists_descriptor ,
 550 .Fn nvlist_exists_binary ,
 551 .Fn nvlist_exists_bool_array ,
 552 .Fn nvlist_exists_number_array ,
 553 .Fn nvlist_exists_string_array ,
 554 .Fn nvlist_exists_nvlist_array ,
 555 .Fn nvlist_exists_descriptor_array
 556 functions return
 557 .Dv true
 558 if element of the given name and the given type determined by the function name
 559 exists or
 560 .Dv false
 561 otherwise.
 562 The nvlist must not be in error state.
 563 .Pp
 564 The
 565 .Fn nvlist_add_null ,
 566 .Fn nvlist_add_bool ,
 567 .Fn nvlist_add_number ,
 568 .Fn nvlist_add_string ,
 569 .Fn nvlist_add_stringf ,
 570 .Fn nvlist_add_stringv ,
 571 .Fn nvlist_add_nvlist ,
 572 .Fn nvlist_add_descriptor ,
 573 .Fn nvlist_add_binary ,
 574 .Fn nvlist_add_bool_array ,
 575 .Fn nvlist_add_number_array ,
 576 .Fn nvlist_add_string_array ,
 577 .Fn nvlist_add_nvlist_array ,
 578 .Fn nvlist_add_descriptor_array
 579 functions add element to the given nvlist.
 580 When adding string or binary buffor the functions will allocate memory
 581 and copy the data over.
 582 When adding nvlist, the nvlist will be cloned and clone will be added.
 583 When adding descriptor, the descriptor will be duplicated using the
 584 .Xr dup 2
 585 system call and the new descriptor will be added.
 586 The array functions will fail if there are any
 587 .Dv NULL
 588 elements in the array, or if the array pointer is
 589 .Dv NULL .
 590 If an error occurs while adding new element, internal error is set which can be
 591 examined using the
 592 .Fn nvlist_error
 593 function.
 594 .Pp
 595 The
 596 .Fn nvlist_move_string ,
 597 .Fn nvlist_move_nvlist ,
 598 .Fn nvlist_move_descriptor ,
 599 .Fn nvlist_move_binary ,
 600 .Fn nvlist_move_bool_array ,
 601 .Fn nvlist_move_number_array ,
 602 .Fn nvlist_move_string_array ,
 603 .Fn nvlist_move_nvlist_array ,
 604 .Fn nvlist_move_descriptor_array
 605 functions add new element to the given nvlist, but unlike
 606 .Fn nvlist_add_<type>
 607 functions they will consume the given resource.
 608 In the case of strings, descriptors, or nvlists every elements must be
 609 unique, or it could cause a double free.
 610 The array functions will fail if there are any
 611 .Dv NULL
 612 elements, or if the array pointer is
 613 .Dv NULL .
 614 If an error occurs while adding new element, the resource is destroyed and
 615 internal error is set which can be examined using the
 616 .Fn nvlist_error
 617 function.
 618 .Pp
 619 The
 620 .Fn nvlist_get_bool ,
 621 .Fn nvlist_get_number ,
 622 .Fn nvlist_get_string ,
 623 .Fn nvlist_get_nvlist ,
 624 .Fn nvlist_get_descriptor ,
 625 .Fn nvlist_get_binary ,
 626 .Fn nvlist_get_bool_array ,
 627 .Fn nvlist_get_number_array ,
 628 .Fn nvlist_get_string_array ,
 629 .Fn nvlist_get_nvlist_array ,
 630 .Fn nvlist_get_descriptor_array
 631 functions return the value that corresponds to the given key name.
 632 In the case of strings, nvlists, descriptors, binary, or arrays, the returned
 633 resource should not be modified - they still belong to the nvlist.
 634 If an element of the given name does not exist, the program will be aborted.
 635 To avoid this, the caller should check for the existence of the name before
 636 trying to obtain the value, or use the
 637 .Xr dnvlist 3
 638 extension, which can provide a default value in the case of a missing element.
 639 The nvlist must not be in error state.
 640 .Pp
 641 The
 642 .Fn nvlist_get_parent
 643 function returns the parent nvlist of the nested nvlist.
 644 .Pp
 645 The
 646 .Fn nvlist_get_array_next
 647 function returns the next element from the array or
 648 .Dv NULL
 649 if the nvlist is not in array or it is the last element.
 650 Note that
 651 .Fn nvlist_get_array_next
 652 only works if you added the nvlist array using the
 653 .Fn nvlist_move_nvlist_array
 654 or
 655 .Fn nvlist_add_nvlist_array
 656 functions.
 657 .Pp
 658 The
 659 .Fn nvlist_get_pararr
 660 function returns the next element in the array, or if not available
 661 the parent of the nested nvlist.
 662 .Pp
 663 The
 664 .Fn nvlist_take_bool ,
 665 .Fn nvlist_take_number ,
 666 .Fn nvlist_take_string ,
 667 .Fn nvlist_take_nvlist ,
 668 .Fn nvlist_take_descriptor ,
 669 .Fn nvlist_take_binary ,
 670 .Fn nvlist_take_bool_array ,
 671 .Fn nvlist_take_number_array ,
 672 .Fn nvlist_take_string_array ,
 673 .Fn nvlist_take_nvlist_array ,
 674 .Fn nvlist_take_descriptor_array
 675 functions return value associated with the given name and remove the element
 676 from the nvlist.
 677 In case of string and binary values, the caller is responsible for free returned
 678 memory using the
 679 .Xr free 3
 680 function.
 681 In case of nvlist, the caller is responsible for destroying returned nvlist
 682 using the
 683 .Fn nvlist_destroy
 684 function.
 685 In case of descriptor, the caller is responsible for closing returned descriptor
 686 using the
 687 .Fn close 2
 688 system call.
 689 If an element of the given name does not exist, the program will be aborted.
 690 To avoid that the caller should check for the existence of the given name
 691 before trying to obtain the value, or use the
 692 .Xr dnvlist 3
 693 extension, which can provide a default value in the case of a missing element.
 694 In the case of an array of strings or binary values, the caller is responsible
 695 for freeing every element of the array using the
 696 .Xr free 3
 697 function.
 698 In the case of an array of nvlists, the caller is responsible for destroying
 699 every element of array using the
 700 .Fn nvlist_destroy
 701 function.
 702 In the case of descriptors, the caller is responsible for closing every
 703 element of array using the
 704 .Fn close 2
 705 system call.
 706 In every case involving an array, the caller must also free the pointer to
 707 the array using the
 708 .Xr free 3
 709 function.
 710 The nvlist must not be in error state.
 711 .Pp
 712 The
 713 .Fn nvlist_free
 714 function removes element of the given name from the nvlist (besides of its type)
 715 and frees all resources associated with it.
 716 If element of the given name does not exist, the program will be aborted.
 717 The nvlist must not be in error state.
 718 .Pp
 719 The
 720 .Fn nvlist_free_type
 721 function removes element of the given name and the given type from the nvlist
 722 and frees all resources associated with it.
 723 If element of the given name and the given type does not exist, the program
 724 will be aborted.
 725 The nvlist must not be in error state.
 726 .Pp
 727 The
 728 .Fn nvlist_free_null ,
 729 .Fn nvlist_free_bool ,
 730 .Fn nvlist_free_number ,
 731 .Fn nvlist_free_string ,
 732 .Fn nvlist_free_nvlist ,
 733 .Fn nvlist_free_descriptor ,
 734 .Fn nvlist_free_binary ,
 735 .Fn nvlist_free_bool_array ,
 736 .Fn nvlist_free_number_array ,
 737 .Fn nvlist_free_string_array ,
 738 .Fn nvlist_free_nvlist_array ,
 739 .Fn nvlist_free_descriptor_array
 740 functions remove element of the given name and the given type determined by the
 741 function name from the nvlist and free all resources associated with it.
 742 If element of the given name and the given type does not exist, the program
 743 will be aborted.
 744 The nvlist must not be in error state.
 745 .Sh EXAMPLES
 746 The following example demonstrates how to prepare an nvlist and send it over
 747 .Xr unix 4
 748 domain socket.
 749 .Bd -literal
 750 nvlist_t *nvl;
 751 int fd;
 752
 753 fd = open("/tmp/foo", O_RDONLY);
 754 if (fd < 0)
 755         err(1, "open(\\"/tmp/foo\\") failed");
 756
 757 nvl = nvlist_create(0);
 758 /*
 759  * There is no need to check if nvlist_create() succeeded,
 760  * as the nvlist_add_<type>() functions can cope.
 761  * If it failed, nvlist_send() will fail.
 762  */
 763 nvlist_add_string(nvl, "filename", "/tmp/foo");
 764 nvlist_add_number(nvl, "flags", O_RDONLY);
 765 /*
 766  * We just want to send the descriptor, so we can give it
 767  * for the nvlist to consume (that's why we use nvlist_move
 768  * not nvlist_add).
 769  */
 770 nvlist_move_descriptor(nvl, "fd", fd);
 771 if (nvlist_send(sock, nvl) < 0) {
 772         nvlist_destroy(nvl);
 773         err(1, "nvlist_send() failed");
 774 }
 775 nvlist_destroy(nvl);
 776 .Ed
 777 .Pp
 778 Receiving nvlist and getting data:
 779 .Bd -literal
 780 nvlist_t *nvl;
 781 const char *command;
 782 char *filename;
 783 int fd;
 784
 785 nvl = nvlist_recv(sock, 0);
 786 if (nvl == NULL)
 787         err(1, "nvlist_recv() failed");
 788
 789 /* For command we take pointer to nvlist's buffer. */
 790 command = nvlist_get_string(nvl, "command");
 791 /*
 792  * For filename we remove it from the nvlist and take
 793  * ownership of the buffer.
 794  */
 795 filename = nvlist_take_string(nvl, "filename");
 796 /* The same for the descriptor. */
 797 fd = nvlist_take_descriptor(nvl, "fd");
 798
 799 printf("command=%s filename=%s fd=%d\n", command, filename, fd);
 800
 801 nvlist_destroy(nvl);
 802 free(filename);
 803 close(fd);
 804 /* command was freed by nvlist_destroy() */
 805 .Ed
 806 .Pp
 807 Iterating over nvlist:
 808 .Bd -literal
 809 nvlist_t *nvl;
 810 const char *name;
 811 void *cookie;
 812 int type;
 813
 814 nvl = nvlist_recv(sock, 0);
 815 if (nvl == NULL)
 816         err(1, "nvlist_recv() failed");
 817
 818 cookie = NULL;
 819 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
 820         printf("%s=", name);
 821         switch (type) {
 822         case NV_TYPE_NUMBER:
 823                 printf("%ju", (uintmax_t)nvlist_get_number(nvl, name));
 824                 break;
 825         case NV_TYPE_STRING:
 826                 printf("%s", nvlist_get_string(nvl, name));
 827                 break;
 828         default:
 829                 printf("N/A");
 830                 break;
 831         }
 832         printf("\\n");
 833 }
 834 .Ed
 835 .Pp
 836 Iterating over every nested nvlist:
 837 .Bd -literal
 838 nvlist_t *nvl;
 839 const char *name;
 840 void *cookie;
 841 int type;
 842
 843 nvl = nvlist_recv(sock, 0);
 844 if (nvl == NULL)
 845         err(1, "nvlist_recv() failed");
 846
 847 cookie = NULL;
 848 do {
 849         while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
 850                 if (type == NV_TYPE_NVLIST) {
 851                         nvl = nvlist_get_nvlist(nvl, name);
 852                         cookie = NULL;
 853                 }
 854         }
 855 } while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
 856 .Ed
 857 .Pp
 858 Iterating over every nested nvlist and every nvlist element:
 859 .Bd -literal
 860 nvlist_t *nvl;
 861 const nvlist_t * const *array;
 862 const char *name;
 863 void *cookie;
 864 int type;
 865
 866 nvl = nvlist_recv(sock, 0);
 867 if (nvl == null)
 868         err(1, "nvlist_recv() failed");
 869
 870 cookie = null;
 871 do {
 872         while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
 873                 if (type == NV_TYPE_NVLIST) {
 874                         nvl = nvlist_get_nvlist(nvl, name);
 875                         cookie = NULL;
 876                 } else if (type == NV_TYPE_NVLIST_ARRAY) {
 877                         nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0];
 878                         cookie = NULL;
 879                 }
 880         }
 881 } while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL);
 882 .Ed
 883 .Pp
 884 Or alternatively:
 885 .Bd -literal
 886 nvlist_t *nvl, *tmp;
 887 const nvlist_t * const *array;
 888 const char *name;
 889 void *cookie;
 890 int type;
 891
 892 nvl = nvlist_recv(sock, 0);
 893 if (nvl == null)
 894         err(1, "nvlist_recv() failed");
 895
 896 cooke = NULL;
 897 tmp = nvl;
 898 do {
 899         do {
 900                 nvl = tmp;
 901                 while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
 902                         if (type == NV_TYPE_NVLIST) {
 903                                 nvl = nvlist_get_nvlist(nvl,
 904                                     name);
 905                                 cookie = NULL;
 906                         } else if (type == NV_TYPE_NVLIST_ARRAY) {
 907                                 nvl = nvlist_get_nvlist_array(nvl, name,
 908                                     NULL)[0];
 909                                 cookie = NULL;
 910                         }
 911                 }
 912                 cookie = NULL;
 913         } while ((tmp = nvlist_get_array_next(nvl)) != NULL);
 914 } while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL);
 915 .Ed
 916 .Sh SEE ALSO
 917 .Xr close 2 ,
 918 .Xr dup 2 ,
 919 .Xr open 2 ,
 920 .Xr err 3 ,
 921 .Xr free 3 ,
 922 .Xr printf 3 ,
 923 .Xr unix 4
 924 .Sh HISTORY
 925 The
 926 .Nm libnv
 927 library appeared in
 928 .Fx 11.0 .
 929 .Sh AUTHORS
 930 .An -nosplit
 931 The
 932 .Nm libnv
 933 library was implemented by
 934 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 935 under sponsorship from the FreeBSD Foundation.