Terminate an array and return correct size

The PMIx_Value_unload function follows the format of the data in the
pmix_value_t structure. If the data type in the pmix_value_t:

• is a simple data field (e.g., a size_t), then the function just copies
  the data across. The caller needs to provide the storage for the data.

• is a pointer (e.g., the pmix_envar_t field), then the function malloc's
  the storage for the value, copies the fields into the new storage, and
  returns that storage to the caller. The caller needs to provide storage
  for the pointer to the returned value.

So in other words, the caller needs to provide storage (and a pointer to) the
place where the final data is to be put. If it's a simple data field, the value
will be placed in the provided storage. If it's a complex data field (e.g., a
struct), then the function will place the pointer to that malloc'd data in the
provided storage.

Note that this has an unusual side effect. For example, consider the case where
the pmix_value_t contains a pmix_byte_object_t. In this case, the caller
would need to pass a pmix_byte_object_t to the PMIx_Value_unload function
since the byte object (and not its data) is what is being unloaded. The returned
size, therefore, is the size of a pmix_byte_object_t, not the number of bytes
in the bytes field of the object.

Signed-off-by: Ralph Castain rhc@pmix.org
(cherry picked from commit 4258fdb)

Add a man page on PMIx_Value_unlaod

Explanation of what this function does and how to use
it isn't straightforward, and the Standard lacks sufficient
detail - leaving people a bit confused. So provide a
little more explanation.

Signed-off-by: Ralph Castain rhc@pmix.org
(cherry picked from commit e3c6c9a)

Extend the PMIx_Value_unload man page

Add some examples in an attempt to further
clarify how to use this function.

Signed-off-by: Ralph Castain rhc@pmix.org
(cherry picked from commit 53fce42)

Update man pages to better explain a couple of PMIx functions

Update/extend the man pages for PMIx_Value_unload and
PMIx_Value_get_number to better explain how they operate
and provide examples on their use.

Signed-off-by: Ralph Castain rhc@pmix.org
(cherry picked from commit d75a2bc)