svn commit: r293090 - in user/ngie/stable-10-libnv: . lib/libnv share/man/man9
Garrett Cooper
ngie at FreeBSD.org
Sun Jan 3 08:30:20 UTC 2016
Author: ngie
Date: Sun Jan 3 08:30:18 2016
New Revision: 293090
URL: https://svnweb.freebsd.org/changeset/base/293090
Log:
MFC r285129:
r285129 (by oshogbo):
Move nvlist documentation to the FreeBSD Kernel Developer's sections.
Added:
user/ngie/stable-10-libnv/share/man/man9/nv.9
- copied unchanged from r285129, head/share/man/man9/nv.9
Deleted:
user/ngie/stable-10-libnv/lib/libnv/nv.3
Modified:
user/ngie/stable-10-libnv/ObsoleteFiles.inc
user/ngie/stable-10-libnv/lib/libnv/Makefile
user/ngie/stable-10-libnv/share/man/man9/Makefile
Directory Properties:
user/ngie/stable-10-libnv/ (props changed)
Modified: user/ngie/stable-10-libnv/ObsoleteFiles.inc
==============================================================================
--- user/ngie/stable-10-libnv/ObsoleteFiles.inc Sun Jan 3 08:19:22 2016 (r293089)
+++ user/ngie/stable-10-libnv/ObsoleteFiles.inc Sun Jan 3 08:30:18 2016 (r293090)
@@ -81,6 +81,69 @@ OLD_FILES+=usr/bin/sgsmsg
# 20150702: Remove duplicated nvlist includes.
OLD_FILES+=usr/include/dnv.h
OLD_FILES+=usr/include/nv.h
+# 20150604: Move nvlist man pages to section 9.
+OLD_FILES+=usr/share/man/man3/libnv.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_bool.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_null.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_number.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_stringf.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_add_stringv.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_clone.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_create.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_destroy.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_dump.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_empty.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_error.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_bool.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_null.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_number.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_exists_type.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_fdump.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_flags.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_bool.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_null.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_number.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_free_type.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_bool.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_number.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_parent.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_get_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_move_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_move_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_move_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_move_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_next.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_pack.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_recv.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_send.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_set_error.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_size.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_binary.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_bool.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_descriptor.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_number.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_nvlist.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_take_string.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_unpack.3.gz
+OLD_FILES+=usr/share/man/man3/nvlist_xfer.3.gz
# 20150506
OLD_FILES+=usr/share/man/man9/NDHASGIANT.9.gz
# 20141223: remove in6_gif.h and in_gif.h
Modified: user/ngie/stable-10-libnv/lib/libnv/Makefile
==============================================================================
--- user/ngie/stable-10-libnv/lib/libnv/Makefile Sun Jan 3 08:19:22 2016 (r293089)
+++ user/ngie/stable-10-libnv/lib/libnv/Makefile Sun Jan 3 08:30:18 2016 (r293090)
@@ -15,71 +15,6 @@ SRCS+= msgio.c
SRCS+= nvlist.c
SRCS+= nvpair.c
-MAN+= nv.3
-
-MLINKS+=nv.3 libnv.3 \
- nv.3 nvlist.3
-MLINKS+=nv.3 nvlist_add_binary.3 \
- nv.3 nvlist_add_bool.3 \
- nv.3 nvlist_add_descriptor.3 \
- nv.3 nvlist_add_null.3 \
- nv.3 nvlist_add_number.3 \
- nv.3 nvlist_add_nvlist.3 \
- nv.3 nvlist_add_string.3 \
- nv.3 nvlist_add_stringf.3 \
- nv.3 nvlist_add_stringv.3 \
- nv.3 nvlist_clone.3 \
- nv.3 nvlist_create.3 \
- nv.3 nvlist_destroy.3 \
- nv.3 nvlist_dump.3 \
- nv.3 nvlist_empty.3 \
- nv.3 nvlist_error.3 \
- nv.3 nvlist_exists.3 \
- nv.3 nvlist_exists_binary.3 \
- nv.3 nvlist_exists_bool.3 \
- nv.3 nvlist_exists_descriptor.3 \
- nv.3 nvlist_exists_null.3 \
- nv.3 nvlist_exists_number.3 \
- nv.3 nvlist_exists_nvlist.3 \
- nv.3 nvlist_exists_string.3 \
- nv.3 nvlist_exists_type.3 \
- nv.3 nvlist_fdump.3 \
- nv.3 nvlist_flags.3 \
- nv.3 nvlist_free.3 \
- nv.3 nvlist_free_binary.3 \
- nv.3 nvlist_free_bool.3 \
- nv.3 nvlist_free_descriptor.3 \
- nv.3 nvlist_free_null.3 \
- nv.3 nvlist_free_number.3 \
- nv.3 nvlist_free_nvlist.3 \
- nv.3 nvlist_free_string.3 \
- nv.3 nvlist_free_type.3 \
- nv.3 nvlist_get_binary.3 \
- nv.3 nvlist_get_bool.3 \
- nv.3 nvlist_get_descriptor.3 \
- nv.3 nvlist_get_number.3 \
- nv.3 nvlist_get_nvlist.3 \
- nv.3 nvlist_get_parent.3 \
- nv.3 nvlist_get_string.3 \
- nv.3 nvlist_move_binary.3 \
- nv.3 nvlist_move_descriptor.3 \
- nv.3 nvlist_move_nvlist.3 \
- nv.3 nvlist_move_string.3 \
- nv.3 nvlist_next.3 \
- nv.3 nvlist_pack.3 \
- nv.3 nvlist_recv.3 \
- nv.3 nvlist_send.3 \
- nv.3 nvlist_set_error.3 \
- nv.3 nvlist_size.3 \
- nv.3 nvlist_take_binary.3 \
- nv.3 nvlist_take_bool.3 \
- nv.3 nvlist_take_descriptor.3 \
- nv.3 nvlist_take_number.3 \
- nv.3 nvlist_take_nvlist.3 \
- nv.3 nvlist_take_string.3 \
- nv.3 nvlist_unpack.3 \
- nv.3 nvlist_xfer.3
-
WARNS?= 6
.if ${MK_TESTS} != "no"
Modified: user/ngie/stable-10-libnv/share/man/man9/Makefile
==============================================================================
--- user/ngie/stable-10-libnv/share/man/man9/Makefile Sun Jan 3 08:19:22 2016 (r293089)
+++ user/ngie/stable-10-libnv/share/man/man9/Makefile Sun Jan 3 08:30:18 2016 (r293090)
@@ -188,6 +188,7 @@ MAN= accept_filter.9 \
mutex.9 \
namei.9 \
netisr.9 \
+ nv.9 \
osd.9 \
panic.9 \
pbuf.9 \
@@ -1002,6 +1003,68 @@ MLINKS+=mutex.9 mtx_assert.9 \
mutex.9 mtx_unlock_spin_flags.9
MLINKS+=namei.9 NDFREE.9 \
namei.9 NDINIT.9
+MLINKS+=nv.9 libnv.9 \
+ nv.9 nvlist.9 \
+ nv.9 nvlist_add_binary.9 \
+ nv.9 nvlist_add_bool.9 \
+ nv.9 nvlist_add_descriptor.9 \
+ nv.9 nvlist_add_null.9 \
+ nv.9 nvlist_add_number.9 \
+ nv.9 nvlist_add_nvlist.9 \
+ nv.9 nvlist_add_string.9 \
+ nv.9 nvlist_add_stringf.9 \
+ nv.9 nvlist_add_stringv.9 \
+ nv.9 nvlist_clone.9 \
+ nv.9 nvlist_create.9 \
+ nv.9 nvlist_destroy.9 \
+ nv.9 nvlist_dump.9 \
+ nv.9 nvlist_empty.9 \
+ nv.9 nvlist_error.9 \
+ nv.9 nvlist_exists.9 \
+ nv.9 nvlist_exists_binary.9 \
+ nv.9 nvlist_exists_bool.9 \
+ nv.9 nvlist_exists_descriptor.9 \
+ nv.9 nvlist_exists_null.9 \
+ nv.9 nvlist_exists_number.9 \
+ nv.9 nvlist_exists_nvlist.9 \
+ nv.9 nvlist_exists_string.9 \
+ nv.9 nvlist_exists_type.9 \
+ nv.9 nvlist_fdump.9 \
+ nv.9 nvlist_flags.9 \
+ nv.9 nvlist_free.9 \
+ nv.9 nvlist_free_binary.9 \
+ nv.9 nvlist_free_bool.9 \
+ nv.9 nvlist_free_descriptor.9 \
+ nv.9 nvlist_free_null.9 \
+ nv.9 nvlist_free_number.9 \
+ nv.9 nvlist_free_nvlist.9 \
+ nv.9 nvlist_free_string.9 \
+ nv.9 nvlist_free_type.9 \
+ nv.9 nvlist_get_binary.9 \
+ nv.9 nvlist_get_bool.9 \
+ nv.9 nvlist_get_descriptor.9 \
+ nv.9 nvlist_get_number.9 \
+ nv.9 nvlist_get_nvlist.9 \
+ nv.9 nvlist_get_parent.9 \
+ nv.9 nvlist_get_string.9 \
+ nv.9 nvlist_move_binary.9 \
+ nv.9 nvlist_move_descriptor.9 \
+ nv.9 nvlist_move_nvlist.9 \
+ nv.9 nvlist_move_string.9 \
+ nv.9 nvlist_next.9 \
+ nv.9 nvlist_pack.9 \
+ nv.9 nvlist_recv.9 \
+ nv.9 nvlist_send.9 \
+ nv.9 nvlist_set_error.9 \
+ nv.9 nvlist_size.9 \
+ nv.9 nvlist_take_binary.9 \
+ nv.9 nvlist_take_bool.9 \
+ nv.9 nvlist_take_descriptor.9 \
+ nv.9 nvlist_take_number.9 \
+ nv.9 nvlist_take_nvlist.9 \
+ nv.9 nvlist_take_string.9 \
+ nv.9 nvlist_unpack.9 \
+ nv.9 nvlist_xfer.9
MLINKS+=panic.9 vpanic.9
MLINKS+=pbuf.9 getpbuf.9 \
pbuf.9 relpbuf.9 \
Copied: user/ngie/stable-10-libnv/share/man/man9/nv.9 (from r285129, head/share/man/man9/nv.9)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ user/ngie/stable-10-libnv/share/man/man9/nv.9 Sun Jan 3 08:30:18 2016 (r293090, copy of r285129, head/share/man/man9/nv.9)
@@ -0,0 +1,691 @@
+.\"
+.\" Copyright (c) 2013 The FreeBSD Foundation
+.\" All rights reserved.
+.\"
+.\" This documentation was written by Pawel Jakub Dawidek under sponsorship
+.\" the FreeBSD Foundation.
+.\"
+.\" 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 4, 2015
+.Dt NV 9
+.Os
+.Sh NAME
+.Nm nvlist_create ,
+.Nm nvlist_destroy ,
+.Nm nvlist_error ,
+.Nm nvlist_set_error ,
+.Nm nvlist_empty ,
+.Nm nvlist_flags ,
+.Nm nvlist_exists ,
+.Nm nvlist_free ,
+.Nm nvlist_clone ,
+.Nm nvlist_dump ,
+.Nm nvlist_fdump ,
+.Nm nvlist_size ,
+.Nm nvlist_pack ,
+.Nm nvlist_unpack ,
+.Nm nvlist_send ,
+.Nm nvlist_recv ,
+.Nm nvlist_xfer ,
+.Nm nvlist_next ,
+.Nm nvlist_add ,
+.Nm nvlist_move ,
+.Nm nvlist_get ,
+.Nm nvlist_take
+.Nd "library for name/value pairs"
+.Sh LIBRARY
+.Lb libnv
+.Sh SYNOPSIS
+.In nv.h
+.Ft "nvlist_t *"
+.Fn nvlist_create "int flags"
+.Ft void
+.Fn nvlist_destroy "nvlist_t *nvl"
+.Ft int
+.Fn nvlist_error "const nvlist_t *nvl"
+.Ft void
+.Fn nvlist_set_error "nvlist_t *nvl, int error"
+.Ft bool
+.Fn nvlist_empty "const nvlist_t *nvl"
+.Ft int
+.Fn nvlist_flags "const nvlist_t *nvl"
+.\"
+.Ft "nvlist_t *"
+.Fn nvlist_clone "const nvlist_t *nvl"
+.\"
+.Ft void
+.Fn nvlist_dump "const nvlist_t *nvl, int fd"
+.Ft void
+.Fn nvlist_fdump "const nvlist_t *nvl, FILE *fp"
+.\"
+.Ft size_t
+.Fn nvlist_size "const nvlist_t *nvl"
+.Ft "void *"
+.Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep"
+.Ft "nvlist_t *"
+.Fn nvlist_unpack "const void *buf" "size_t size" "int flags"
+.\"
+.Ft int
+.Fn nvlist_send "int sock" "const nvlist_t *nvl"
+.Ft "nvlist_t *"
+.Fn nvlist_recv "int sock" "int flags"
+.Ft "nvlist_t *"
+.Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags"
+.\"
+.Ft "const char *"
+.Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep"
+.\"
+.Ft bool
+.Fn nvlist_exists "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type"
+.Ft bool
+.Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name"
+.\"
+.Ft void
+.Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value"
+.Ft void
+.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value"
+.Ft void
+.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value"
+.Ft void
+.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..."
+.Ft void
+.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap"
+.Ft void
+.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value"
+.Ft void
+.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value"
+.Ft void
+.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size"
+.\"
+.Ft void
+.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
+.Ft void
+.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value"
+.Ft void
+.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value"
+.Ft void
+.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size"
+.\"
+.Ft bool
+.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
+.Ft uint64_t
+.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name"
+.Ft "const char *"
+.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name"
+.Ft "const nvlist_t *"
+.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name"
+.Ft int
+.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name"
+.Ft "const void *"
+.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep"
+.Ft "const nvlist_t *"
+.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
+.\"
+.Ft bool
+.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
+.Ft uint64_t
+.Fn nvlist_take_number "nvlist_t *nvl" "const char *name"
+.Ft "char *"
+.Fn nvlist_take_string "nvlist_t *nvl" "const char *name"
+.Ft "nvlist_t *"
+.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name"
+.Ft int
+.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name"
+.Ft "void *"
+.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep"
+.\"
+.Ft void
+.Fn nvlist_free "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type"
+.\"
+.Ft void
+.Fn nvlist_free_null "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_bool "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_number "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_string "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
+.Sh DESCRIPTION
+The
+.Nm libnv
+library allows to easily manage name value pairs as well as send and receive
+them over sockets.
+A group (list) of name value pairs is called an
+.Nm nvlist .
+The API supports the following data types:
+.Bl -ohang -offset indent
+.It Sy null ( NV_TYPE_NULL )
+There is no data associated with the name.
+.It Sy bool ( NV_TYPE_BOOL )
+The value can be either
+.Dv true
+or
+.Dv false .
+.It Sy number ( NV_TYPE_NUMBER )
+The value is a number stored as
+.Vt uint64_t .
+.It Sy string ( NV_TYPE_STRING )
+The value is a C string.
+.It Sy nvlist ( NV_TYPE_NVLIST )
+The value is a nested nvlist.
+.It Sy descriptor ( NV_TYPE_DESCRIPTOR )
+The value is a file descriptor.
+Note that file descriptors can be sent only over
+.Xr unix 4
+domain sockets.
+.It Sy binary ( NV_TYPE_BINARY )
+The value is a binary buffer.
+.El
+.Pp
+The
+.Fn nvlist_create
+function allocates memory and initializes an nvlist.
+.Pp
+The following flag can be provided:
+.Pp
+.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent
+.It Dv NV_FLAG_IGNORE_CASE
+Perform case-insensitive lookups of provided names.
+.It Dv NV_FLAG_NO_UNIQUE
+Names in the nvlist do not have to be unique.
+.El
+.Pp
+The
+.Fn nvlist_destroy
+function destroys the given nvlist.
+Function does nothing if
+.Dv NULL
+nvlist is provided.
+Function never modifies the
+.Va errno
+global variable.
+.Pp
+The
+.Fn nvlist_error
+function returns any error value that the nvlist accumulated.
+If the given nvlist is
+.Dv NULL
+the
+.Er ENOMEM
+error will be returned.
+.Pp
+The
+.Fn nvlist_set_error
+function sets an nvlist to be in the error state.
+Subsequent calls to
+.Fn nvlist_error
+will return the given error value.
+This function cannot be used to clear the error state from an nvlist.
+This function does nothing if the nvlist is already in the error state.
+.Pp
+The
+.Fn nvlist_empty
+function returns
+.Dv true
+if the given nvlist is empty and
+.Dv false
+otherwise.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_flags
+function returns flags used to create the nvlist with the
+.Fn nvlist_create
+function.
+.Pp
+The
+.Fn nvlist_clone
+functions clones the given nvlist.
+The clone shares no resources with its origin.
+This also means that all file descriptors that are part of the nvlist will be
+duplicated with the
+.Xr dup 2
+system call before placing them in the clone.
+.Pp
+The
+.Fn nvlist_dump
+dumps nvlist content for debugging purposes to the given file descriptor
+.Fa fd .
+.Pp
+The
+.Fn nvlist_fdump
+dumps nvlist content for debugging purposes to the given file stream
+.Fa fp .
+.Pp
+The
+.Fn nvlist_size
+function returns the size of the given nvlist after converting it to binary
+buffer with the
+.Fn nvlist_pack
+function.
+.Pp
+The
+.Fn nvlist_pack
+function converts the given nvlist to a binary buffer.
+The function allocates memory for the buffer, which should be freed with the
+.Xr free 3
+function.
+If the
+.Fa sizep
+argument is not
+.Dv NULL ,
+the size of the buffer will be stored there.
+The function returns
+.Dv NULL
+in case of an error (allocation failure).
+If the nvlist contains any file descriptors
+.Dv NULL
+will be returned.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_unpack
+function converts the given buffer to the nvlist.
+The
+.Fa flags
+argument defines what type of the top level nvlist is expected to be.
+Flags are set up using the
+.Fn nvlist_create
+function.
+If the nvlist flags do not match the flags passed to
+.Fn nvlist_unpack ,
+the nvlist will not be returned.
+Every nested nvlist list should be checked using
+.Fn nvlist_flags
+function.
+The function returns
+.Dv NULL
+in case of an error.
+.Pp
+The
+.Fn nvlist_send
+function sends the given nvlist over the socket given by the
+.Fa sock
+argument.
+Note that nvlist that contains file descriptors can only be send over
+.Xr unix 4
+domain sockets.
+.Pp
+The
+.Fn nvlist_recv
+function receives nvlist over the socket given by the
+.Fa sock
+argument.
+The
+.Fa flags
+argument defines what type of the top level nvlist is expected to be.
+Flags are set up using the
+.Fn nvlist_create
+function.
+If the nvlist flags do not match the flags passed to
+.Fn nvlist_recv ,
+the nvlist will not be returned.
+Every nested nvlist list should be checked using
+.Fn nvlist_flags
+function.
+.Pp
+The
+.Fn nvlist_xfer
+function sends the given nvlist over the socket given by the
+.Fa sock
+argument and receives nvlist over the same socket.
+The
+.Fa flags
+argument defines what type of the top level nvlist is expected to be.
+Flags are set up using the
+.Fn nvlist_create
+function.
+If the nvlist flags do not match the flags passed to
+.Fn nvlist_xfer ,
+the nvlist will not be returned.
+Every nested nvlist list should be checked using
+.Fn nvlist_flags
+function.
+The given nvlist is always destroyed.
+.Pp
+The
+.Fn nvlist_next
+function iterates over the given nvlist returning names and types of subsequent
+elements.
+The
+.Fa cookiep
+argument allows the function to figure out which element should be returned
+next.
+The
+.Va *cookiep
+should be set to
+.Dv NULL
+for the first call and should not be changed later.
+Returning
+.Dv NULL
+means there are no more elements on the nvlist.
+The
+.Fa typep
+argument can be NULL.
+Elements may not be removed from the nvlist while traversing it.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_exists
+function returns
+.Dv true
+if element of the given name exists (besides of its type) or
+.Dv false
+otherwise.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_exists_type
+function returns
+.Dv true
+if element of the given name and the given type exists or
+.Dv false
+otherwise.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_exists_null ,
+.Fn nvlist_exists_bool ,
+.Fn nvlist_exists_number ,
+.Fn nvlist_exists_string ,
+.Fn nvlist_exists_nvlist ,
+.Fn nvlist_exists_descriptor ,
+.Fn nvlist_exists_binary
+functions return
+.Dv true
+if element of the given name and the given type determined by the function name
+exists or
+.Dv false
+otherwise.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_add_null ,
+.Fn nvlist_add_bool ,
+.Fn nvlist_add_number ,
+.Fn nvlist_add_string ,
+.Fn nvlist_add_stringf ,
+.Fn nvlist_add_stringv ,
+.Fn nvlist_add_nvlist ,
+.Fn nvlist_add_descriptor ,
+.Fn nvlist_add_binary
+functions add element to the given nvlist.
+When adding string or binary buffor the functions will allocate memory
+and copy the data over.
+When adding nvlist, the nvlist will be cloned and clone will be added.
+When adding descriptor, the descriptor will be duplicated using the
+.Xr dup 2
+system call and the new descriptor will be added.
+If an error occurs while adding new element, internal error is set which can be
+examined using the
+.Fn nvlist_error
+function.
+.Pp
+The
+.Fn nvlist_move_string ,
+.Fn nvlist_move_nvlist ,
+.Fn nvlist_move_descriptor ,
+.Fn nvlist_move_binary
+functions add new element to the given nvlist, but unlike
+.Fn nvlist_add_<type>
+functions they will consume the given resource.
+If an error occurs while adding new element, the resource is destroyed and
+internal error is set which can be examined using the
+.Fn nvlist_error
+function.
+.Pp
+The
+.Fn nvlist_get_bool ,
+.Fn nvlist_get_number ,
+.Fn nvlist_get_string ,
+.Fn nvlist_get_nvlist ,
+.Fn nvlist_get_descriptor ,
+.Fn nvlist_get_binary
+functions allow to obtain value of the given name.
+In case of string, nvlist, descriptor or binary, returned resource should
+not be modified - it still belongs to the nvlist.
+If element of the given name does not exist, the program will be aborted.
+To avoid that the caller should check for existence before trying to obtain
+the value or use
+.Xr dnvlist 3
+extension, which allows to provide default value for a missing element.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_get_parent
+function allows to obtain the parent nvlist from the nested nvlist.
+.Pp
+The
+.Fn nvlist_take_bool ,
+.Fn nvlist_take_number ,
+.Fn nvlist_take_string ,
+.Fn nvlist_take_nvlist ,
+.Fn nvlist_take_descriptor ,
+.Fn nvlist_take_binary
+functions return value associated with the given name and remove the element
+from the nvlist.
+In case of string and binary values, the caller is responsible for free returned
+memory using the
+.Xr free 3
+function.
+In case of nvlist, the caller is responsible for destroying returned nvlist
+using the
+.Fn nvlist_destroy
+function.
+In case of descriptor, the caller is responsible for closing returned descriptor
+using the
+.Fn close 2
+system call.
+If element of the given name does not exist, the program will be aborted.
+To avoid that the caller should check for existence before trying to obtain
+the value or use
+.Xr dnvlist 3
+extension, which allows to provide default value for a missing element.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_free
+function removes element of the given name from the nvlist (besides of its type)
+and frees all resources associated with it.
+If element of the given name does not exist, the program will be aborted.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_free_type
+function removes element of the given name and the given type from the nvlist
+and frees all resources associated with it.
+If element of the given name and the given type does not exist, the program
+will be aborted.
+The nvlist must not be in error state.
+.Pp
+The
+.Fn nvlist_free_null ,
+.Fn nvlist_free_bool ,
+.Fn nvlist_free_number ,
+.Fn nvlist_free_string ,
+.Fn nvlist_free_nvlist ,
+.Fn nvlist_free_descriptor ,
+.Fn nvlist_free_binary
+functions remove element of the given name and the given type determined by the
+function name from the nvlist and free all resources associated with it.
+If element of the given name and the given type does not exist, the program
+will be aborted.
+The nvlist must not be in error state.
+.Sh EXAMPLES
+The following example demonstrates how to prepare an nvlist and send it over
+.Xr unix 4
+domain socket.
+.Bd -literal
+nvlist_t *nvl;
+int fd;
+
+fd = open("/tmp/foo", O_RDONLY);
+if (fd < 0)
+ err(1, "open(\\"/tmp/foo\\") failed");
+
+nvl = nvlist_create(0);
+/*
+ * There is no need to check if nvlist_create() succeeded,
+ * as the nvlist_add_<type>() functions can cope.
+ * If it failed, nvlist_send() will fail.
+ */
+nvlist_add_string(nvl, "filename", "/tmp/foo");
+nvlist_add_number(nvl, "flags", O_RDONLY);
+/*
+ * We just want to send the descriptor, so we can give it
+ * for the nvlist to consume (that's why we use nvlist_move
+ * not nvlist_add).
+ */
+nvlist_move_descriptor(nvl, "fd", fd);
+if (nvlist_send(sock, nvl) < 0) {
+ nvlist_destroy(nvl);
+ err(1, "nvlist_send() failed");
+}
+nvlist_destroy(nvl);
+.Ed
+.Pp
+Receiving nvlist and getting data:
+.Bd -literal
+nvlist_t *nvl;
+const char *command;
+char *filename;
+int fd;
+
+nvl = nvlist_recv(sock, 0);
+if (nvl == NULL)
+ err(1, "nvlist_recv() failed");
+
+/* For command we take pointer to nvlist's buffer. */
+command = nvlist_get_string(nvl, "command");
+/*
+ * For filename we remove it from the nvlist and take
+ * ownership of the buffer.
+ */
+filename = nvlist_take_string(nvl, "filename");
+/* The same for the descriptor. */
+fd = nvlist_take_descriptor(nvl, "fd");
+
+printf("command=%s filename=%s fd=%d\n", command, filename, fd);
+
+nvlist_destroy(nvl);
+free(filename);
+close(fd);
+/* command was freed by nvlist_destroy() */
+.Ed
+.Pp
+Iterating over nvlist:
+.Bd -literal
+nvlist_t *nvl;
+const char *name;
+void *cookie;
+int type;
+
+nvl = nvlist_recv(sock, 0);
+if (nvl == NULL)
+ err(1, "nvlist_recv() failed");
+
+cookie = NULL;
+while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
+ printf("%s=", name);
+ switch (type) {
+ case NV_TYPE_NUMBER:
+ printf("%ju", (uintmax_t)nvlist_get_number(nvl, name));
+ break;
+ case NV_TYPE_STRING:
+ printf("%s", nvlist_get_string(nvl, name));
+ break;
+ default:
+ printf("N/A");
+ break;
+ }
+ printf("\\n");
+}
+.Ed
+.Pp
+Iterating over every nested nvlist:
+.Bd -literal
+nvlist_t *nvl;
+const char *name;
+void *cookie;
+int type;
+
+nvl = nvlist_recv(sock, 0);
+if (nvl == NULL)
+ err(1, "nvlist_recv() failed");
+
+cookie = NULL;
+do {
+ while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
+ if (type == NV_TYPE_NVLIST) {
+ nvl = nvlist_get_nvlist(nvl, name);
+ cookie = NULL;
+ }
+ }
+} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
+.Ed
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr dup 2 ,
+.Xr open 2 ,
+.Xr err 3 ,
+.Xr free 3 ,
+.Xr printf 3 ,
+.Xr unix 4
+.Sh HISTORY
+The
+.Nm libnv
+library appeared in
+.Fx 11.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm libnv
+library was implemented by
+.An Pawel Jakub Dawidek Aq Mt pawel at dawidek.net
+under sponsorship from the FreeBSD Foundation.
More information about the svn-src-user
mailing list