lib/37838: proplib documentation enhancements

[ekamperi%gmail.com@localhost]

>Number:         37838
>Category:       lib
>Synopsis:       proplib documentation enhancements
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    lib-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Jan 21 21:00:00 +0000 2008
>Originator:     Stathis Kamperis
>Release:        NetBSD 4.99.18 i386
>Organization:
>Environment:
NetBSD bahar.aydogan.net 4.99.18 NetBSD 4.99.18 (GENERIC) #74: Sat Apr 28 
16:59:34 CEST 2007  
zafer@h950596:/home/zafer/netbsd/usr/objdir/sys/arch/i386/compile/GENERIC i386

>Description:
1) For some functions it is not documented what they return if they
fail. Some indicative examples are:

prop_array_create_with_capacity()
prop_array_internalize_from_file()
prop_string_create_cstring()

Most of these return NULL on failure which sounds pretty reasonable
and predictable, but still, shouldn't it be explicitly documented ?

2) There are a couple of typo errors in prop_data(3) and in 
prop_copyin_ioctl(9).

3) It would be nice if prop_send_ioctl(3) and prop_copyin_ioctl(9) had explicit 
categories RETURN VALUES, ERRORS and EXAMPLES.

4) prop_array_add() doesn't mention how array expands if its count exceeds its 
capacity (i.e. newcapacity = oldcapacity + EXPAND_STEP)
>How-To-Repeat:

>Fix:
The following patch addresses the aforementioned issues:

Index: prop_array.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_array.3,v
retrieving revision 1.6
diff -u -r1.6 prop_array.3
--- prop_array.3        6 Nov 2007 11:41:35 -0000       1.6
+++ prop_array.3        10 Jan 2008 18:49:23 -0000
@@ -120,10 +120,16 @@
 .It Fn prop_array_create "void"
 Create an empty array.
 The array initially has no capacity.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_array_create_with_capacity "unsigned int capacity"
 Create an array with the capacity to store
 .Fa capacity
 objects.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_array_copy "prop_array_t array"
 Copy an array.
 The new array has an initial capacity equal to the number of objects stored
@@ -132,6 +138,9 @@
 copies of those objects
 .Pq i.e. a shallow copy is made .
 If the original array is immutable, the resulting array is also immutable.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_array_copy_mutable "prop_array_t array"
 Like
 .Fn prop_array_copy ,
@@ -139,8 +148,10 @@
 .It Fn prop_array_capacity "prop_array_t array"
 Returns the total capacity of the array, including objects already stored
 in the array.
+If the supplied object isn't an array, zero is returned.
 .It Fn prop_array_count "prop_array_t array"
 Returns the number of objects stored in the array.
+If the supplied object isn't an array, zero is returned.
 .It Fn prop_array_ensure_capacity "prop_array_t array" "unsigned int capacity"
 Ensure that the array has a total capacity of
 .Fa capacity ,
@@ -159,6 +170,9 @@
 An array iterator returns the object references stored in the array.
 Storing to or removing from the array invalidates any active iterators for
 the array.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_array_make_immutable "prop_array_t array"
 Make
 .Fa array
@@ -170,6 +184,9 @@
 .It Fn prop_array_get "prop_array_t array" "unsigned int index"
 Return the object stored at the array index
 .Fa index .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_array_set "prop_array_t array" "unsigned int index" \
        "prop_object_t obj"
 Store a reference to the object
@@ -198,6 +215,14 @@
 if storing the object was successful and
 .Dv false
 otherwise.
+.Pp
+During expansion, array's capacity is augmented by the
+.Dv EXPAND_STEP
+constant, as defined in
+.Pa libprop/prop_array.c
+file, e.g.
+.Pp
+#define        EXPAND_STEP             16
 .It Fn prop_array_remove "prop_array_t array" "unsigned int index"
 Remove the reference to the object stored at array index
 .Fa index .
@@ -207,6 +232,9 @@
 Returns
 .Dv true
 if the two arrays are equivalent.
+If at least one of the supplied objects isn't an array,
+.Dv false
+is returned.
 Note: Objects contained in the array are compared by value, not by reference.
 .It Fn prop_array_externalize "prop_array_t array"
 Externalizes an array, returning a NUL-terminated buffer containing
@@ -245,6 +273,9 @@
 Reads the XML property list contained in the file specified by
 .Fa path ,
 internalizes it, and returns the corresponding array.
+Returns
+.Dv NULL
+on failure.
 .El
 .Sh SEE ALSO
 .Xr prop_bool 3 ,
Index: prop_bool.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_bool.3,v
retrieving revision 1.3
diff -u -r1.3 prop_bool.3
--- prop_bool.3 16 Aug 2007 16:30:59 -0000      1.3
+++ prop_bool.3 10 Jan 2008 18:49:23 -0000
@@ -65,8 +65,14 @@
 .Fa val .
 .It Fn prop_bool_copy "prop_bool_t bool"
 Copy a boolean value object.
+If the supplied object isn't a boolean,
+.Dv NULL
+is returned.
 .It Fn prop_bool_true "prop_bool_t bool"
 Returns the value of the boolean value object.
+If the supplied object isn't a boolean,
+.Dv false
+is returned.
 .El
 .Sh SEE ALSO
 .Xr prop_array 3 ,
Index: prop_copyin_ioctl.9
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_copyin_ioctl.9,v
retrieving revision 1.2
diff -u -r1.2 prop_copyin_ioctl.9
--- prop_copyin_ioctl.9 22 Apr 2007 11:23:29 -0000      1.2
+++ prop_copyin_ioctl.9 10 Jan 2008 18:49:23 -0000
@@ -68,12 +68,42 @@
 to and from the kernel using
 .Xr ioctl 2 .
 .Pp
-A kernel ioctl routine receivig or returning a property list will be passed a
+A kernel ioctl routine receiving or returning a property list will be passed a
 pointer to a
 .Vt struct plistref .
 This structure encapsulates the reference to the property list in externalized
 form.
+.Sh RETURN VALUES
+If successful, functions return zero. Otherwise, an error number will be 
returned to indicate the error.
+.Sh ERRORS
+.Fn prop_array_copyin_ioctl
+and
+.Fn prop_dictionary_copyin_ioctl
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+Bad address
+.It Bq Er EIO
+Input/output error
+.It Bq Er ENOMEM
+Cannot allocate memory
+.It Bq Er ENOTSUP
+Not supported
+.El
 .Pp
+.Fn prop_array_copyout_ioctl
+and
+.Fn prop_dictionary_copyout_ioctl
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+Bad address
+.It Bq Er ENOMEM
+Cannot allocate memory
+.It Bq Er ENOTSUP
+Not supported
+.El
+.Sh EXAMPLES
 The following
 .Pq simplified
 example demonstrates using
Index: prop_data.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_data.3,v
retrieving revision 1.4
diff -u -r1.4 prop_data.3
--- prop_data.3 16 Aug 2007 16:31:00 -0000      1.4
+++ prop_data.3 10 Jan 2008 18:49:23 -0000
@@ -82,20 +82,34 @@
 .Fa blob
 with size
 .Fa len .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_data_create_data_nocopy "const void *blob" "size_t len"
 Create a data object that contains a reference to
 .Fa blob
 with size
 .Fa len .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_data_copy "prop_data_t data"
 Copy a data object.
-If the the data object being copied is an external data reference,
+If the data object being copied is an external data reference,
 then the copy also references the same external data.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_data_size "prop_data_t data"
 Returns the size of the data object.
+If the supplied object isn't a data object, zero is returned.
 .It Fn prop_data_data "prop_data_t data"
 Returns a copy of the data object's contents.
 The caller is responsible for freeing the returned buffer.
+If the supplied object isn't a data object or
+if the data container is empty,
+.Dv NULL
+is returned.
 .Pp
 In user space, the buffer is allocated using
 .Xr malloc 3 .
@@ -105,10 +119,16 @@
 .Dv M_TEMP .
 .It Fn prop_data_data_nocopy "prop_data_t data"
 Returns an immutable reference to the contents of the data object.
+If the supplied object isn't a data object,
+.Dv NULL
+is returned.
 .It Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2"
 Returns
 .Dv true
 if the two data objects are equivalent.
+If at least one of the supplied objects isn't a data object,
+.Dv false
+is returned.
 .It Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len"
 Returns
 .Dv true
@@ -116,6 +136,9 @@
 .Fa blob
 with size
 .Fa len .
+If the supplied object isn't a data object,
+.Dv false
+is returned.
 .El
 .Sh SEE ALSO
 .Xr prop_array 3 ,
Index: prop_dictionary.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_dictionary.3,v
retrieving revision 1.10
diff -u -r1.10 prop_dictionary.3
--- prop_dictionary.3   5 Jan 2008 00:23:46 -0000       1.10
+++ prop_dictionary.3   10 Jan 2008 18:49:23 -0000
@@ -142,10 +142,16 @@
 .It Fn prop_dictionary_create "void"
 Create an empty dictionary.
 The dictionary initially has no capacity.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_dictionary_create_with_capacity "unsigned int capacity"
 Create a dictionary with the capacity to store
 .Fa capacity
 objects.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_dictionary_copy "prop_dictionary_t dict"
 Copy a dictionary.
 The new dictionary has an initial capacity equal to the number of objects
@@ -155,12 +161,16 @@
 .Pq i.e. a shallow copy is made .
 If the original dictionary is immutable, the resulting dictionary is also
 immutable.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_dictionary_copy_mutable "prop_dictionary_t dict"
 Like
 .Fn prop_dictionary_copy ,
 except the resulting dictionary is always mutable.
 .It Fn prop_dictionary_count "prop_dictionary_t dict"
 Returns the number of objects stored in the dictionary.
+If the supplied object isn't a dictionary, zero is returned.
 .It Fn prop_dictionary_ensure_capacity "prop_dictionary_t dict"
 Ensure that the dictionary has a total capacity of
 .Fa capacity ,
@@ -173,6 +183,9 @@
 and
 .Dv false
 otherwise.
+If the supplied object isn't a dictionary,
+.Dv false
+is returned.
 .It Fn prop_dictionary_iterator "prop_dictionary_t dict"
 Create an iterator for the dictionary.
 The dictionary is retained by the iterator.
@@ -181,6 +194,9 @@
 key symbol must be performed.
 Storing to or removing from the dictionary invalidates any active iterators for
 the dictionary.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_dictionary_all_keys "prop_dictionary_t dict"
 Return an array of all of the dictionary key symbols
 .Pq prop_dictionary_keysym_t
@@ -189,6 +205,9 @@
 retaining the ability to mutate the dictionary; instead of iterating
 over the dictionary itself, iterate over the array of keys.
 The caller is responsible for releasing the array.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_dictionary_make_immutable "prop_dictionary_t dict"
 Make
 .Fa dict
@@ -300,6 +319,9 @@
 Reads the XML property list contained in the file specified by
 .Fa path ,
 internalizes it, and returns the corresponding array.
+Returns
+.Dv NULL
+on failure.
 .El
 .Sh SEE ALSO
 .Xr prop_array 3 ,
Index: prop_ingest.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_ingest.3,v
retrieving revision 1.3
diff -u -r1.3 prop_ingest.3
--- prop_ingest.3       16 Aug 2007 16:31:00 -0000      1.3
+++ prop_ingest.3       10 Jan 2008 18:49:23 -0000
@@ -145,6 +145,9 @@
 .Fa private
 may be used to pass application-specific context to the ingest handlers.
 Note that an ingest context can be re-used to perform multiple ingests.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_ingest_context_free "prop_ingest_context_t ctx"
 Free an ingest context.
 .It Fn prop_ingest_context_error "prop_ingest_context_t ctx"
Index: prop_number.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_number.3,v
retrieving revision 1.7
diff -u -r1.7 prop_number.3
--- prop_number.3       16 Aug 2007 16:31:00 -0000      1.7
+++ prop_number.3       10 Jan 2008 18:49:23 -0000
@@ -131,37 +131,70 @@
 .It Fn prop_number_create_integer "int64_t val"
 Create a numeric value object with the signed value
 .Fa val .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_number_create_unsigned_integer "uint64_t val"
 Create a numeric value object with the unsigned value
 .Fa val .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_number_copy "prop_number_t number"
 Copy a numeric value object.
+If the supplied object isn't a numeric value,
+.Dv NULL
+is returned.
 .It Fn prop_number_size "prop_number_t number"
 Returns 8, 16, 32, or 64, representing the number of bits required to
 hold the value of the object.
+If the supplied object isn't a numeric value,
+.Dv NULL
+is returned.
 .It Fn prop_number_unsigned "prop_number_t number"
 Returns
 .Dv true
 if the numeric value object has an unsigned value.
 .It Fn prop_number_integer_value "prop_number_t number"
 Returns the signed integer value of the numeric value object.
+If the supplied object isn't a numeric value, zero is returned. Thus,
+it is not possible to distinguish between ``not a prop_number_t''
+and ``prop_number_t has a value of 0''.
 .It Fn prop_number_unsigned_integer_value "prop_number_t number"
 Returns the unsigned integer value of the numeric value object.
+If the supplied object isn't a numeric value, zero is returned. Thus,
+it is not possible to distinguish between ``not a prop_number_t''
+and ``prop_number_t has a value of 0''.
 .It Fn prop_number_equals "prop_number_t num1" "prop_number_t num2"
 Returns
 .Dv true
 if the two numeric value objects are equivalent.
+If at least one of the supplied objects isn't a numeric value,
+.Dv false
+is returned.
 .It Fn prop_number_equals_integer "prop_number_t number" "int64_t val"
 Returns
 .Dv true
 if the object's value is equivalent to the signed value
 .Fa val .
+If the supplied object isn't a numerical value or if
+.Fa val
+exceeds
+.Dv INT64_MAX ,
+.Dv false
+is returned.
 .It Fn prop_number_equals_unsigned_integer "prop_number_t number" \
     "uint64_t val"
 Returns
 .Dv true
 if the object's value is equivalent to the unsigned value
 .Fa val .
+If the supplied object isn't a numerical value or if
+.Fa val
+exceeds
+.Dv INT64_MAX ,
+.Dv false
+is returned.
 .El
 .Sh SEE ALSO
 .Xr prop_array 3 ,
Index: prop_send_ioctl.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_send_ioctl.3,v
retrieving revision 1.3
diff -u -r1.3 prop_send_ioctl.3
--- prop_send_ioctl.3   10 May 2007 22:15:47 -0000      1.3
+++ prop_send_ioctl.3   10 Jan 2008 18:49:23 -0000
@@ -69,7 +69,35 @@
 functions implement the user space side of a protocol for sending property
 lists to and from the kernel using
 .Xr ioctl 2 .
+.Sh RETURN VALUES
+If successful, functions return zero. Otherwise, an error number is returned 
to indicate the error.
+.Sh ERRORS
+.Fn prop_array_send_ioctl
+and
+.Fn prop_dictionary_send_ioctl
+will fail if:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+Cannot allocate memory
+.It Bq Er ENOTSUP
+Not supported
+.El
+.Pp
+.Fn prop_array_recv_ioctl
+and
+.Fn prop_dictionary_recv_ioctl
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EIO
+Input/output error
+.It Bq Er ENOTSUP
+Not supported
+.El
 .Pp
+In addition to these,
+.Xr ioctl 2
+errors may be returned.
+.Sh EXAMPLES
 The following
 .Pq simplified
 example demonstrates using
Index: prop_string.3
===================================================================
RCS file: /cvsroot/src/common/lib/libprop/prop_string.3,v
retrieving revision 1.4
diff -u -r1.4 prop_string.3
--- prop_string.3       16 Aug 2007 16:31:00 -0000      1.4
+++ prop_string.3       10 Jan 2008 18:49:23 -0000
@@ -91,24 +91,43 @@
 .Bl -tag -width "xxxxx"
 .It Fn prop_string_create "void"
 Create an empty mutable string.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_create_cstring "const char *cstring"
 Create a mutable string that contains a copy of
 .Fa cstring .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_create_cstring_nocopy "const char *cstring"
 Create an immutable string that contains a reference to
 .Fa cstring .
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_copy "prop_string_t string"
 Copy a string.
 If the the string being copied is an immutable external C string reference,
 then the copy is also immutable and references the same external C string.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_copy_mutable "prop_string_t string"
 Copy a string, always creating a mutable copy.
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_size "prop_string_t string"
 Returns the size of the string, not including the terminating NUL.
+If the supplied object isn't a string, zero is returned.
 .It Fn prop_string_mutable "prop_string_t string"
 Returns
 .Dv true
 if the string is mutable.
+If the supplied object isn't a string,
+.Dv false
+is returned.
 .It Fn prop_string_cstring "prop_string_t string"
 Returns a copy of the string's contents as a C string.
 The caller is responsible for freeing the returned buffer.
@@ -119,9 +138,16 @@
 .Xr malloc 9
 using the malloc type
 .Dv M_TEMP .
+.Pp
+Returns
+.Dv NULL
+on failure.
 .It Fn prop_string_cstring_nocopy "prop_string_t string"
 Returns an immutable reference to the contents of the string as a
 C string.
+If the supplied object isn't a string,
+.Dv NULL
+is returned.
 .It Fn prop_string_append "prop_string_t str1" "prop_string_t str2"
 Append the contents of
 .Fa str2