Add support for the arrays in nvlist library.

- Add
  nvlist_{add,get,take,move,exists,free}_{number,bool,string,nvlist,
  descriptor} functions.
- Add support for (un)packing arrays.
- Add the nvl_array_next field to the nvlist structure.
  If an array is added by the nvlist_{move,add}_nvlist_array function
  this field will contains next element in the array.
- Add the nitems field to the nvpair and nvpair_header structure.
  This field contains number of elements in the array.
- Add special flag (NV_FLAG_IN_ARRAY) which is set if nvlist is a part of
  an array.
- Add special type (NV_TYPE_NVLIST_ARRAY_NEXT).This type is used only
  on packing/unpacking.
- Add new API for traversing arrays (nvlist_get_array_next).
- Add the nvlist_get_pararr function which combines the
  nvlist_get_array_next and nvlist_get_parent functions. If nvlist is in
  the array it will return next element from array. If nvlist is last
  element in array or it isn't in array it will return his
  container (parent). This function should simplify traveling over nvlist.
- Add tests for new features.
- Add documentation for new functions.
- Add my copyright.
- Regenerate the sys/cddl/compat/opensolaris/sys/nvpair.h file.

PR:		191083
Reviewed by:	allanjude (doc)
Approved by:	pjd (mentor)

1 files changed, 253 insertions, 19 deletions

diff --git a/share/man/man9/nv.9 b/share/man/man9/nv.9
index e3d708011177..b5d755f38902 100644
--- a/share/man/man9/nv.9
+++ b/share/man/man9/nv.9
@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 2013 The FreeBSD Foundation
+.\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org>
 .\" All rights reserved.
 .\"
 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
@@ -28,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd Aug 11, 2015
+.Dd August 15, 2015
 .Dt NV 9
 .Os
 .Sh NAME
@@ -49,6 +50,7 @@
 .Nm nvlist_send ,
 .Nm nvlist_recv ,
 .Nm nvlist_xfer ,
+.Nm nvlist_in_array ,
 .Nm nvlist_next ,
 .Nm nvlist_add ,
 .Nm nvlist_move ,
@@ -71,6 +73,8 @@
 .Fn nvlist_empty "const nvlist_t *nvl"
 .Ft int
 .Fn nvlist_flags "const nvlist_t *nvl"
+.Ft bool
+.Fn nvlist_in_array "const nvlist_t *nvl"
 .\"
 .Ft "nvlist_t *"
 .Fn nvlist_clone "const nvlist_t *nvl"
@@ -115,6 +119,16 @@
 .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 bool
+.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name"
+.Ft bool
+.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name"
 .\"
 .Ft void
 .Fn nvlist_add_null "nvlist_t *nvl" "const char *name"
@@ -134,6 +148,20 @@
 .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_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems"
 .\"
 .Ft void
 .Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value"
@@ -143,6 +171,20 @@
 .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 void
+.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems"
+.
+.Ft void
+.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems"
 .\"
 .Ft bool
 .Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name"
@@ -156,8 +198,22 @@
 .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 bool *"
+.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "const uint64_t *"
+.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "const char * const *"
+.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "const nvlist_t * const *"
+.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "const int *"
+.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems"
 .Ft "const nvlist_t *"
 .Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep"
+.Ft "const nvlist_t *"
+.Fn nvlist_get_array_next "const nvlist_t *nvl"
+.Ft "const nvlist_t *"
+.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep"
 .\"
 .Ft bool
 .Fn nvlist_take_bool "nvlist_t *nvl" "const char *name"
@@ -171,6 +227,16 @@
 .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 "bool *"
+.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "uint64_t **"
+.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "char **"
+.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "nvlist_t **"
+.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" "size_t *nitems"
+.Ft "int *"
+.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" "size_t *nitems"
 .\"
 .Ft void
 .Fn nvlist_free "nvlist_t *nvl" "const char *name"
@@ -191,6 +257,16 @@
 .Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name"
 .Ft void
 .Fn nvlist_free_binary "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name"
+.Ft void
+.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name"
 .Sh DESCRIPTION
 The
 .Nm libnv
@@ -221,6 +297,23 @@ Note that file descriptors can be sent only over
 domain sockets.
 .It Sy binary ( NV_TYPE_BINARY )
 The value is a binary buffer.
+.It Sy bool array ( NV_TYPE_BOOL_ARRAY )
+The value is an array of boolean values.
+.It Sy number array ( NV_TYPE_NUMBER_ARRAY )
+The value is an array of numbers, each stored as
+.Vt uint64_t .
+.It Sy string array ( NV_TYPE_STRING_ARRAY )
+The value is an array of C strings.
+.It Sy nvlist array  ( NV_TYPE_NVLIST_ARRAY )
+The value is an array of nvlists.
+When an nvlist is added to an array, it becomes part of the primary nvlist.
+Traversing these arrays can be done using the
+.Fn nvlist_get_array_next
+and
+.Fn nvlist_get_pararr
+functions.
+.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY )
+The value is an array of files descriptors.
 .El
 .Pp
 The
@@ -280,6 +373,14 @@ function returns flags used to create the nvlist with the
 function.
 .Pp
 The
+.Fn nvlist_in_array
+function returns
+.Dv true
+if
+.Fa nvl
+is part of an array that is a member of another nvlist.
+.Pp
+The
 .Fn nvlist_clone
 functions clones the given nvlist.
 The clone shares no resources with its origin.
@@ -446,7 +547,12 @@ The
 .Fn nvlist_exists_string ,
 .Fn nvlist_exists_nvlist ,
 .Fn nvlist_exists_descriptor ,
-.Fn nvlist_exists_binary
+.Fn nvlist_exists_binary ,
+.Fn nvlist_exists_bool_array ,
+.Fn nvlist_exists_number_array ,
+.Fn nvlist_exists_string_array ,
+.Fn nvlist_exists_nvlist_array ,
+.Fn nvlist_exists_descriptor_array
 functions return
 .Dv true
 if element of the given name and the given type determined by the function name
@@ -464,7 +570,12 @@ The
 .Fn nvlist_add_stringv ,
 .Fn nvlist_add_nvlist ,
 .Fn nvlist_add_descriptor ,
-.Fn nvlist_add_binary
+.Fn nvlist_add_binary ,
+.Fn nvlist_add_bool_array ,
+.Fn nvlist_add_number_array ,
+.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 buffor the functions will allocate memory
 and copy the data over.
@@ -472,6 +583,10 @@ 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.
+The array functions will 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
 examined using the
 .Fn nvlist_error
@@ -481,10 +596,21 @@ The
 .Fn nvlist_move_string ,
 .Fn nvlist_move_nvlist ,
 .Fn nvlist_move_descriptor ,
-.Fn nvlist_move_binary
+.Fn nvlist_move_binary ,
+.Fn nvlist_move_bool_array ,
+.Fn nvlist_move_number_array ,
+.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
 .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
+.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
 .Fn nvlist_error
@@ -496,20 +622,43 @@ The
 .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
+.Fn nvlist_get_binary ,
+.Fn nvlist_get_bool_array ,
+.Fn nvlist_get_number_array ,
+.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 allows to provide default value for a missing element.
+extension, which can provide a default value in the case of 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.
+function returns the parent nvlist of the nested nvlist.
+.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
+or
+.Fn nvlist_add_nvlist_array
+functions.
+.Pp
+The
+.Fn nvlist_get_pararr
+function returns the next element in the array, or if not available
+the parent of the nested nvlist.
 .Pp
 The
 .Fn nvlist_take_bool ,
@@ -517,7 +666,12 @@ The
 .Fn nvlist_take_string ,
 .Fn nvlist_take_nvlist ,
 .Fn nvlist_take_descriptor ,
-.Fn nvlist_take_binary
+.Fn nvlist_take_binary ,
+.Fn nvlist_take_bool_array ,
+.Fn nvlist_take_number_array ,
+.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
@@ -532,11 +686,27 @@ 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
+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 allows to provide default value for a missing element.
+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
+.Xr free 3
+function.
 The nvlist must not be in error state.
 .Pp
 The
@@ -561,7 +731,12 @@ The
 .Fn nvlist_free_string ,
 .Fn nvlist_free_nvlist ,
 .Fn nvlist_free_descriptor ,
-.Fn nvlist_free_binary
+.Fn nvlist_free_binary ,
+.Fn nvlist_free_bool_array ,
+.Fn nvlist_free_number_array ,
+.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
@@ -679,6 +854,65 @@ do {
 	}
 } while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL);
 .Ed
+.Pp
+Iterating over every nested nvlist and every nvlist element:
+.Bd -literal
+nvlist_t *nvl;
+const nvlist_t * const *array;
+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;
+		} else if (type == NV_TYPE_NVLIST_ARRAY) {
+			nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0];
+			cookie = NULL;
+		}
+	}
+} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL);
+.Ed
+.Pp
+Or alternatively:
+.Bd -literal
+nvlist_t *nvl, *tmp;
+const nvlist_t * const *array;
+const char *name;
+void *cookie;
+int type;
+
+nvl = nvlist_recv(sock, 0);
+if (nvl == null)
+	err(1, "nvlist_recv() failed");
+
+cooke = NULL;
+tmp = nvl;
+do {
+	do {
+		nvl = tmp;
+		while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) {
+			if (type == NV_TYPE_NVLIST) {
+				nvl = nvlist_get_nvlist(nvl,
+				    name);
+				cookie = NULL;
+			} else if (type == NV_TYPE_NVLIST_ARRAY) {
+				nvl = nvlist_get_nvlist_array(nvl, name,
+				    NULL)[0];
+				cookie = NULL;
+			}
+		}
+		cookie = NULL;
+	} while ((tmp = nvlist_get_array_next(nvl)) != NULL);
+} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL);
+.Ed
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr dup 2 ,