git: ae1cc4182b3f - main - nv.9: Editorial pass
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 03 Jan 2025 15:52:05 UTC
The branch main has been updated by jhb:
URL: https://cgit.FreeBSD.org/src/commit/?id=ae1cc4182b3fa6abe4de85ab201a198917dda73a
commit ae1cc4182b3fa6abe4de85ab201a198917dda73a
Author: John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2025-01-03 15:51:28 +0000
Commit: John Baldwin <jhb@FreeBSD.org>
CommitDate: 2025-01-03 15:51:28 +0000
nv.9: Editorial pass
Various rewording tweaks and clarifications to some behavior (e.g.
nvlist_size doesn't require calling nvlist_pack first).
Reviewed by: pjd
Sponsored by: Chelsio Communications
Differential Revision: https://reviews.freebsd.org/D48256
---
share/man/man9/cnv.9 | 36 ++--
share/man/man9/dnv.9 | 26 +--
share/man/man9/nv.9 | 482 +++++++++++++++++++++++++++++++--------------------
3 files changed, 330 insertions(+), 214 deletions(-)
diff --git a/share/man/man9/cnv.9 b/share/man/man9/cnv.9
index de37c8271eb9..fa5310e174e1 100644
--- a/share/man/man9/cnv.9
+++ b/share/man/man9/cnv.9
@@ -23,14 +23,14 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd June 18, 2018
+.Dd January 3, 2025
.Dt CNV 9
.Os
.Sh NAME
.Nm cnvlist_get ,
.Nm cnvlist_take ,
.Nm cnvlist_free
-.Nd "API for managing name/value pairs by cookie."
+.Nd "API for managing name/value pairs by cookie"
.Sh LIBRARY
.Lb libnv
.Sh SYNOPSIS
@@ -115,7 +115,7 @@ The
.Nm libnv
library permits easy management of name/value pairs and can send and receive
them over sockets.
-For more information, also see
+For more information, see
.Xr nv 9 .
.Pp
The concept of cookies is explained in
@@ -128,25 +128,28 @@ from
.Pp
The
.Fn cnvlist_name
-function returns the name of an element associated with the given cookie.
+function returns the name of an element associated with
+.Fa cookie .
.Pp
The
.Fn cnvlist_type
-function returns the type of an element associated with the given cookie.
+function returns the type of an element associated with
+.Fa cookie .
Types which can be returned are described in
.Xr nv 9 .
.Pp
The
.Nm cnvlist_get
-family of functions obtains the value associated with the given cookie.
+functions return the value associated with
+.Fa cookie .
Returned strings, nvlists, descriptors, binaries, or arrays must not be modified
-by the user, since they still belong to the nvlist.
+by the user since they still belong to the nvlist.
The nvlist must not be in an error state.
.Pp
The
.Nm cnvlist_take
-family of functions returns the value associated with the given cookie and
-removes the element from the nvlist.
+functions return the value associated with the given cookie and
+remove the element from the nvlist.
When the value is a string, binary, or array value, the caller is responsible
for freeing the returned memory with
.Fn free 3 .
@@ -154,18 +157,21 @@ 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 the
+returned descriptor with
.Fn close 2 .
.Pp
The
.Nm cnvlist_free
-family of functions removes an element of the supplied cookie and frees all
-resources.
-If an element of the given cookie has the wrong type or does not exist, the
+functions remove the element identified by
+.Fa cookie
+and free any associated resources.
+If the element identified by
+.Fa cookie
+has the wrong type or does not exist, the
program
-is aborted.
+aborts.
.Sh EXAMPLES
-The following example demonstrates how to deal with cnvlist API.
+The following example demonstrates how to deal with the cnvlist API.
.Bd -literal
int type;
void *cookie, *scookie, *bcookie;
diff --git a/share/man/man9/dnv.9 b/share/man/man9/dnv.9
index 8c89d6599801..16f603df8392 100644
--- a/share/man/man9/dnv.9
+++ b/share/man/man9/dnv.9
@@ -23,13 +23,13 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd July 26, 2016
+.Dd January 3, 2025
.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."
+.Nd "API for getting name/value pairs with a default value"
.Sh LIBRARY
.Lb libnv
.Sh SYNOPSIS
@@ -63,26 +63,32 @@ The
.Nm libnv
library permits easy management of name/value pairs and can send and receive
them over sockets.
-For more information, also see
+For more information, 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
+functions return the value associated with
+.Fa name .
+If an element named
+.Fa 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.
+by the user since 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
+functions return the value associated with
+.Fa name
+and removes the associated element from
+.Fa nvl .
+If an element named
+.Fa 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
diff --git a/share/man/man9/nv.9 b/share/man/man9/nv.9
index 67c05247fdfb..4e4542c146ef 100644
--- a/share/man/man9/nv.9
+++ b/share/man/man9/nv.9
@@ -27,7 +27,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd February 2, 2023
+.Dd January 3, 2025
.Dt NV 9
.Os
.Sh NAME
@@ -280,11 +280,12 @@
.Sh DESCRIPTION
The
.Nm libnv
-library allows to easily manage name value pairs as well as send and receive
+library permits creating and managing name value pairs as well as
+sending and receiving
them over sockets.
A group (list) of name value pairs is called an
.Nm nvlist .
-The API supports the following data types:
+The API supports the following data types for values:
.Bl -ohang -offset indent
.It Sy null ( NV_TYPE_NULL )
There is no data associated with the name.
@@ -330,7 +331,7 @@ The
.Fn nvlist_create
function allocates memory and initializes an nvlist.
.Pp
-The following flag can be provided:
+The following flags can be provided:
.Pp
.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent
.It Dv NV_FLAG_IGNORE_CASE
@@ -342,28 +343,36 @@ Names in the nvlist do not have to be unique.
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.
+This function does nothing if
+.Fa nvl
+is
+.Dv NULL .
+This function never modifies
+.Va errno .
.Pp
The
.Fn nvlist_error
-function returns any error value that the nvlist accumulated.
-If the given nvlist is
-.Dv NULL
-the
+function returns the first error set on
+.Fa nvl .
+If
+.Fa nvl
+is not in the error state,
+this function returns zero.
+If
+.Fa nvl
+is
+.Dv NULL ,
.Er ENOMEM
-error will be returned.
+is returned.
.Pp
The
.Fn nvlist_set_error
-function sets an nvlist to be in the error state.
+function sets an the error value for
+.Fa nvl .
Subsequent calls to
.Fn nvlist_error
-will return the given error value.
+will return
+.Fa error .
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
@@ -371,16 +380,24 @@ The
.Fn nvlist_empty
function returns
.Dv true
-if the given nvlist is empty and
+if
+.Fa nvl
+is empty and
.Dv false
otherwise.
-The nvlist must not be in error state.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_flags
-function returns flags used to create the nvlist with the
-.Fn nvlist_create
-function.
+function returns the flags used to create
+.Fa nvl
+with the
+.Fn nvlist_create ,
+.Fn nvlist_recv ,
+.Fn nvlist_unpack ,
+or
+.Fn nvlist_xfer
+functions.
.Pp
The
.Fn nvlist_in_array
@@ -392,7 +409,8 @@ is part of an array that is a member of another nvlist.
.Pp
The
.Fn nvlist_clone
-functions clones the given nvlist.
+function clones
+.Fa nvl .
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
@@ -401,154 +419,170 @@ system call before placing them in the clone.
.Pp
The
.Fn nvlist_dump
-dumps nvlist content for debugging purposes to the given file descriptor
+function dumps nvlist content for debugging purposes to the file descriptor
.Fa fd .
.Pp
The
.Fn nvlist_fdump
-dumps nvlist content for debugging purposes to the given file stream
+dumps nvlist content for debugging purposes to the 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
+function returns the size of the binary buffer that would be generated by 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
+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
+the size of the buffer is stored there.
+This 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.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_unpack
-function converts the given buffer to the nvlist.
+function converts a binary buffer to a new 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
+argument has the same meaning as the
+.Fa flags
+argument passed to
+.Fn nvlist_create .
+If
+.Fa flags
+do not match the flags used to create the initial nvlist before it was packed,
+this function will fail.
+The flags of nested nvlists are not validated by this function.
+The caller is responsible for validating the flags on any nested nvlists using
+.Fn nvlist_flags .
+This function returns the new nvlist on success or
.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
+function sends
+.Fa nvl
+over the socket
+.Fa sock .
+Note that nvlists that contain file descriptors can only be sent over
.Xr unix 4
domain sockets.
.Pp
The
.Fn nvlist_recv
-function receives nvlist over the socket given by the
-.Fa sock
-argument.
-The
+function receives an nvlist over the socket
+.Fa sock .
+As with
+.Fn nvlist_unpack ,
+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.
+argument is used to construct the new nvlist and must match the flags used
+to construct the original nvlist written to
+.Fa sock
+by the peer.
+The flags of nested nvlists are not validated by this function.
+The caller is responsible for validating the flags on any nested nvlists using
+.Fn nvlist_flags .
+This function returns the new nvlist on success or
+.Dv NULL
+in case of an error.
.Pp
The
.Fn nvlist_xfer
-function sends the given nvlist over the socket given by the
+function sends
+.Fa nvl
+over the socket
.Fa sock
-argument and receives nvlist over the same socket.
+argument and then receives a new 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.
+argument applies to the new nvlist similar to
+.Fn nvlist_recv .
+The nvlist
+.Fa nvl
+is always destroyed.
+This function returns the new nvlist on success or
+.Dv NULL
+in case of an error.
.Pp
The
.Fn nvlist_next
-function iterates over the given nvlist returning names and types of subsequent
+function iterates over
+.Fa nvl
+returning the names and types of subsequent
elements.
The
.Fa cookiep
-argument allows the function to figure out which element should be returned
-next.
-The
+argument determines which element is returned.
+If
.Va *cookiep
-should be set to
-.Dv NULL
-for the first call and should not be changed later.
-Returning
+is
+.Dv NULL ,
+the values for the first element in the list are returned.
+Otherwise,
+.Va *cookiep
+should contain the result of a prior call to
+.Fn nvlist_next
+in which case values for the next element from
+.Fa nvl
+are returned.
+This function returns
.Dv NULL
-means there are no more elements on the nvlist.
+when there are no more elements on
+.Fa nvl .
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.
-Note that
-.Fn nvlist_next
-will handle
-.Va cookiep
-being set to
+argument can be
.Dv NULL .
-In this case first element is returned or
-.Dv NULL
-if nvlist is empty.
-This behavior simplifies removing the first element from the list.
+Elements may not be removed from
+.Fa nvl
+the nvlist while traversing it.
+.Fa nvl
+must not be in the error state.
+Additional actions can be performed on an element identified by a cookie
+via the
+.Xr cnv 9
+API .
.Pp
The
.Fn nvlist_exists
function returns
.Dv true
-if element of the given name exists (besides of its type) or
+if an element named
+.Fa name
+exists in
+.Fa nvl
+(regardless of type) or
.Dv false
otherwise.
-The nvlist must not be in error state.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_exists_type
function returns
.Dv true
-if element of the given name and the given type exists or
+if an element named
+.Fa name
+of type
+.Fa type
+exists or
.Dv false
otherwise.
-The nvlist must not be in error state.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_exists_null ,
@@ -565,11 +599,13 @@ The
.Fn nvlist_exists_descriptor_array
functions return
.Dv true
-if element of the given name and the given type determined by the function name
+if element named
+.Fa name
+with the type determined by the function name
exists or
.Dv false
otherwise.
-The nvlist must not be in error state.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_add_null ,
@@ -586,18 +622,23 @@ The
.Fn nvlist_add_string_array ,
.Fn nvlist_add_nvlist_array ,
.Fn nvlist_add_descriptor_array
-functions add element to the given nvlist.
-When adding string or binary buffer 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
+functions add an element to
+.Fa nvl .
+When adding a string or binary buffer, these functions allocate memory
+and copy the data.
+When adding an nvlist, the
+.Fa value
+nvlist is cloned and the clone is added to
+.Fa nvl .
+When adding a file descriptor, the descriptor is duplicated via the
.Xr dup 2
-system call and the new descriptor will be added.
-The array functions will fail if there are any
+system call and the new file descriptor is added.
+The array functions fail if there are any
.Dv NULL
elements in the array, or if the array pointer is
.Dv NULL .
-If an error occurs while adding new element, internal error is set which can be
+If an error occurs while adding a new element,
+an internal error is set which can be
examined using the
.Fn nvlist_error
function.
@@ -612,17 +653,27 @@ The
.Fn nvlist_move_string_array ,
.Fn nvlist_move_nvlist_array ,
.Fn nvlist_move_descriptor_array
-functions add new element to the given nvlist, but unlike
+functions add an element to
+.Fa nvl ,
+but unlike the
.Fn nvlist_add_<type>
-functions they will consume the given resource.
-In the case of strings, descriptors, or nvlists every elements must be
-unique, or it could cause a double free.
-The array functions will fail if there are any
+functions they consume the given resource.
+For string, file descriptor, binary buffer, or nvlist values,
+no value should be moved into an nvlist multiple times;
+doing so will cause that value to be freed multiple times.
+Note that strings or binary buffers must be allocated with
+.Xr malloc 3 ,
+and the pointers will be released via
+.Xr free 3
+when
+.Fa nvl
+is destroyed.
+The array functions fail if there are any
.Dv NULL
elements, or if the array pointer is
.Dv NULL .
If an error occurs while adding new element, the resource is destroyed and
-internal error is set which can be examined using the
+an internal error is set which can be examined using the
.Fn nvlist_error
function.
.Pp
@@ -638,37 +689,61 @@ The
.Fn nvlist_get_string_array ,
.Fn nvlist_get_nvlist_array ,
.Fn nvlist_get_descriptor_array
-functions return the value that corresponds to the given key name.
-In the case of strings, nvlists, descriptors, binary, or arrays, the returned
-resource should not be modified - they still belong to the nvlist.
-If an element of the given name does not exist, the program will be aborted.
-To avoid this, the caller should check for the existence of the name before
-trying to obtain the value, or use the
-.Xr dnvlist 3
-extension, which can provide a default value in the case of a missing element.
-The nvlist must not be in error state.
+functions return the value of the first element in
+.Fa nvl
+named
+.Fa name .
+For string, nvlist, file descriptor, binary buffer, or array values,
+the returned resource must not be modified - it still belongs to
+.Fa nvl .
+.Pp
+If an element named
+.Fa name
+does not exist, the program aborts.
+To avoid this, the caller should check for the existence of the element before
+trying to obtain the value or use the
+.Xr dnv 9
+extension which provides a default value in the case of a missing element.
+.Pp
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_get_parent
-function returns the parent nvlist of the nested nvlist.
+function returns the parent nvlist of
+.Fa nvl .
.Pp
The
.Fn nvlist_get_array_next
-function returns the next element from the array or
-.Dv NULL
-if the nvlist is not in array or it is the last element.
-Note that
-.Fn nvlist_get_array_next
-only works if you added the nvlist array using the
-.Fn nvlist_move_nvlist_array
+function returns the next element after
+.Fa nvl
+from an array of nvlists.
+If
+.Fa nvl
+is not in an array of nvlists or it is the last element,
+this function returns
+.Dv NULL .
+An nvlist is only in an nvlist array if it was added to an nvlist array using
+.Fn nvlist_add_nvlist_array ,
+.Fn nvlist_append_nvlist_array ,
or
-.Fn nvlist_add_nvlist_array
-functions.
+.Fn nvlist_move_nvlist_array .
.Pp
The
.Fn nvlist_get_pararr
-function returns the next element in the array, or if not available
-the parent of the nested nvlist.
+function returns the next element after
+.Fn nvl
+from an array of nvlists.
+If
+.Fn nvl
+is the last element in an array of nvlists,
+the parent nvlist of
+.Fa nvl is
+returned.
+If
+.Fn nvl
+is not in an array of nvlists,
+.Dv NULL
+is returned.
.Pp
The
.Fn nvlist_take_bool ,
@@ -682,42 +757,38 @@ The
.Fn nvlist_take_string_array ,
.Fn nvlist_take_nvlist_array ,
.Fn nvlist_take_descriptor_array
-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
+functions return the value of the element named
+.Fa name
+and remove the element from
+.Fa nvl .
+For string and binary buffer values, the caller is responsible for freeing
+the returned value using the
.Xr free 3
function.
-In case of nvlist, the caller is responsible for destroying returned nvlist
+For nvlist values, the caller is responsible for destroying the returned nvlist
using the
.Fn nvlist_destroy
function.
-In case of descriptor, the caller is responsible for closing returned descriptor
+For file descriptor values, the caller is responsible for closing the
+returned descriptor
using the
.Fn close 2
system call.
-If an element of the given name does not exist, the program will be aborted.
-To avoid that the caller should check for the existence of the given name
-before trying to obtain the value, or use the
-.Xr dnvlist 3
-extension, which can provide a default value in the case of a missing element.
-In the case of an array of strings or binary values, the caller is responsible
-for freeing every element of the array using the
-.Xr free 3
-function.
-In the case of an array of nvlists, the caller is responsible for destroying
-every element of array using the
-.Fn nvlist_destroy
-function.
-In the case of descriptors, the caller is responsible for closing every
-element of array using the
-.Fn close 2
-system call.
-In every case involving an array, the caller must also free the pointer to
-the array using the
+For array values, the caller is responsible for destroying every element of
+the array based on the element type.
+In addition, the caller must also free the pointer to the array using the
.Xr free 3
function.
-The nvlist must not be in error state.
+.Pp
+If an element named
+.Fa name
+does not exist, the program aborts.
+To avoid this, the caller should check for the existence of the element before
+trying to obtain the value or use the
+.Xr dnv 9
+extension which provides a default value in the case of a missing element.
+.Pp
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_append_bool_array ,
@@ -725,28 +796,46 @@ The
.Fn nvlist_append_string_array ,
.Fn nvlist_append_nvlist_array ,
.Fn nvlist_append_descriptor_array
-functions append an element to the existing array using the same semantics
-as the add functions (i.e. the element will be copied when applicable).
-If the array for a given key does not exist, then it will be created
+functions append an element to an existing array using the same semantics
+as the add functions (that is, the element will be copied when applicable).
+If the array named
+.Fa name
+does not exist, then it will be created
as if using the
.Fn nvlist_add_<type>_array
function.
-The internal error is set on append failure.
+If an error occurs while appending a new element,
+an internal error is set on
+.Fa nvl .
.Pp
The
.Fn nvlist_free
-function removes element of the given name from the nvlist (besides of its type)
+function removes the first element named
+.Fa name
+from
+.Fa nvl
+(regardless of 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.
+If no element named
+.Fa name
+exists, the program aborts.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_free_type
-function removes element of the given name and the given type from the nvlist
+function removes the first element named
+.Fa name
+of type
+.Fa type
+from
+.Fa nvl
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.
+If no element named
+.Fa name
+of type
+.Fa type
+exists, the program aborts.
+The nvlist must not be in the error state.
.Pp
The
.Fn nvlist_free_null ,
@@ -761,20 +850,31 @@ The
.Fn nvlist_free_string_array ,
.Fn nvlist_free_nvlist_array ,
.Fn nvlist_free_descriptor_array
-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.
+functions remove the first element named
+.Fa name
+with the type determined by the function name from
+.Fa nvl
+free all resources associated with it.
+If no element named
+.Fa name
+with the appropriate type exists, the program aborts.
+The nvlist must not be in the error state.
.Sh NOTES
The
.Fn nvlist_pack
and
.Fn nvlist_unpack
-functions handle the byte-order conversions, so the binary buffer can be
-packed/unpacked by the hosts with the different endianness.
+functions handle byte-order conversions, so binary buffers can be
+packed and unpacked on hosts with different endianness.
+.Pp
+The
+.Fn nvlist_recv ,
+.Fn nvlist_send ,
+and
+.Fn nvlist_xfer
+functions can transfer nvlists between hosts with different endianness.
.Sh EXAMPLES
-The following example demonstrates how to prepare an nvlist and send it over
+The following example demonstrates how to prepare an nvlist and send it over a
.Xr unix 4
domain socket.
.Bd -literal
@@ -786,16 +886,18 @@ if (fd < 0)
err(1, "open(\\"/tmp/foo\\") failed");
nvl = nvlist_create(0);
+
/*
- * There is no need to check if nvlist_create() succeeded,
+ * 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
+ * for the nvlist to consume (that is why we use nvlist_move
* not nvlist_add).
*/
nvlist_move_descriptor(nvl, "fd", fd);
@@ -806,7 +908,7 @@ if (nvlist_send(sock, nvl) < 0) {
nvlist_destroy(nvl);
.Ed
.Pp
-Receiving nvlist and getting data:
+Receiving an nvlist and retrieving element values:
.Bd -literal
nvlist_t *nvl;
const char *command;
@@ -817,25 +919,27 @@ nvl = nvlist_recv(sock, 0);
if (nvl == NULL)
err(1, "nvlist_recv() failed");
-/* For command we take pointer to nvlist's buffer. */
+/* For command we accept a pointer to the nvlist's internal 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. */
+
+/* The same for the file descriptor. */
fd = nvlist_take_descriptor(nvl, "fd");
printf("command=%s filename=%s fd=%d\n", command, filename, fd);
+/* command is freed by nvlist_destroy() */
nvlist_destroy(nvl);
free(filename);
close(fd);
-/* command was freed by nvlist_destroy() */
.Ed
.Pp
-Iterating over nvlist:
+Iterating over an nvlist:
.Bd -literal
nvlist_t *nvl;
const char *name;
@@ -898,7 +1002,7 @@ nvl = nvlist_recv(sock, 0);
if (nvl == null)
err(1, "nvlist_recv() failed");
-cookie = null;
+cookie = NULL;
do {
while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
if (type == NV_TYPE_NVLIST) {