man page updates to align with latest API changes and craigs feedback

doc/getdns_address.3.in

@@ -40,11 +40,11 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_address
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
 void *userarg,
 .br
@@ -56,15 +56,13 @@ getdns_callback_t callbackfn)
 getdns_return_t 
 .br
 .B getdns_address_sync
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
-uint32_t *response_length,
+getdns_dict **response)
-.br
-struct getdns_dict **response)
 .RE
 
 .SH DESCRIPTION
@@ -102,11 +100,6 @@ populated by the API and used to identify the callback (for example to getdns_ca
 .RP
 pointer to a callback function defined by the application, typically used to process the response, may not be NULL. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback.
 
-.HP 3
-.I response_length
-.RP
-The synchronous entry point includes this argument, the response length is placed at the address pointed to by response_length.
-
 .HP 3
 .I response
 .RP
@@ -123,6 +116,9 @@ Upon successful completion the functions return
 .B GETDNS_RETURN_BAD_CONTEXT 
 if the context pointer is invalid
 .LP
+.B GETDNS_RETURN_INVALID PARAMETER 
+one or more parameters has an invalid value
+.LP
 .B GETDNS_RETURN_BAD_DOMAIN_NAME
 if the domain name passed to the function is invalid
 .LP
@@ -131,6 +127,10 @@ if the data type specified in one or more of the extensions does not match the s
 .LP
 .B GETDNS_RETURN_NO_SUCH_EXTENSION
 if one or more of the strings specified in the extensions are not valid
+.LP
+.B GETDNS_RETURN_GENERIC_ERROR
+some problem was encountered in the function not addressed by one of the more
+specific return codes
 
 The values of status in the response include:
 
@@ -165,10 +165,11 @@ TBD
 .SH SEE ALSO
 .BR libgetdns (3), 
 .BR getdns_context (3), 
+.BR getdns_free_sync_request_memory (3), 
 .BR getdns_general (3), 
 .BR getdns_general_sync (3), 
 .BR getdns_hostname (3), 
 .BR getdns_hostname_sync (3), 
 .BR getdns_service (3), 
-.BR getdns_service_sync (3).
+.BR getdns_service_sync (3)
 

doc/getdns_context.3.in

@@ -43,7 +43,7 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t
 .br
 .B getdns_context_create
-(struct getdns_context ** context,
+(getdns_context ** context,
 .RS 3
 .br
 int set_from_os)
@@ -52,7 +52,7 @@ int set_from_os)
 getdns_return_t
 .br
 .B getdns_context_create_with_memory_functions
-(struct getdns_context ** context,
+(getdns_context ** context,
 .RS 3
 .br
 int set_from_os,
@@ -67,7 +67,7 @@ void (*free) (void *))
 getdns_return_t
 .br
 .B getdns_context_create_with_extended_memory_functions
-(struct getdns_context **context,
+(getdns_context **context,
 .RS 3
 .br
 int set_from_os,
@@ -84,7 +84,7 @@ void (*free) (void *userarg, void *))
 void
 .br
 .B getdns_context_destroy
-(struct getdns_context *context)
+(getdns_context *context)
 
 .SH DESCRIPTION
 

doc/getdns_dict.3.in

@@ -38,7 +38,7 @@ DNS Resolver library (libgetdns, -lgetdns)
 .SH SYNOPSIS
 #include <getdns.h>
 
-struct getdns_dict * 
+getdns_dict * 
 .br
 .B getdns_dict_create
 ()
@@ -46,7 +46,7 @@ struct getdns_dict *
 void 
 .br
 .B getdns_dict_destroy
-(struct getdns_dict *this_dict)
+(getdns_dict *this_dict)
 
 .SH DESCRIPTION
 
@@ -54,11 +54,11 @@ void
 The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_dict_get.3.in

@@ -45,32 +45,60 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_dict_get_bindata
-(struct getdns_dict *this_dict, char *name, struct getdns_bindata **answer)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_bindata **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_get_data_type
-(struct getdns_dict *this_dict, char *name, getdns_data_type *answer)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_data_type *answer)
+.RE
 
 getdns_return_t
 .br
 .B getdns_dict_get_dict
-(struct getdns_dict *this_dict, char *name, struct getdns_dict **answer)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_dict **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_get_int
-(struct getdns_dict *this_dict, char *name, uint32_t *answer)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+uint32_t *answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_get_list
-(struct getdns_dict *this_dict, char *name, struct getdns_list **answer)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_list **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_get_names
-(struct getdns_dict *this_dict, struct getdns_list **answer)
+(getdns_dict *this_dict,
+.RS 3
+getdns_list **answer)
+.RE
 
 .SH DESCRIPTION
 
@@ -78,11 +106,11 @@ getdns_return_t
 The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_dict_set.3.in

@@ -43,22 +43,42 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_dict_set_bindata
-(struct getdns_dict *this_dict, char *name, struct getdns_bindata *child_bindata)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_bindata *child_bindata)
+.RE
 
 getdns_return_t
 .br
 .B getdns_dict_set_dict
-(struct getdns_dict *this_dict, char *name, struct getdns_dict *child_dict)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_dict *child_dict)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_set_int
-(struct getdns_dict *this_dict, char *name, uint32_t child_uint32_t)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+uint32_t child_uint32_t)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_dict_set_list
-(struct getdns_dict *this_dict, char *name, struct getdns_list *child_list)
+(getdns_dict *this_dict,
+.RS 3
+char *name,
+.br
+getdns_list *child_list)
+.RE
 
 .SH DESCRIPTION
 
@@ -66,11 +86,11 @@ getdns_return_t
 The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_free_sync_request_memory.3.in

@@ -39,7 +39,7 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_free_sync_request_memory
-(struct getdns_dict *response)
+(getdns_dict *response)
 
 .SH DESCRIPTION
 

doc/getdns_general.3.in

@@ -40,13 +40,13 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_general
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
 uint16_t request_type
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
 void *userarg,
 .br
@@ -58,17 +58,15 @@ getdns_callback_t callbackfn)
 getdns_return_t 
 .br
 .B getdns_general_sync
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
 uint16_t request_type
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
-uint32_t *response_length,
+getdns_dict **response)
-.br
-struct getdns_dict **response)
 .RE
 
 .SH DESCRIPTION
@@ -113,11 +111,6 @@ populated by the API and used to identify the callback (for example to getdns_ca
 .RP
 pointer to a callback function defined by the application, typically used to process the response, may not be NULL. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback.
 
-.HP 3
-.I response_length
-.RP
-The synchronous entry point includes this argument, the response length is placed at the address pointed to by response_length.
-
 .HP 3
 .I response
 .RP
@@ -134,6 +127,9 @@ Upon successful completion the functions return
 .B GETDNS_RETURN_BAD_CONTEXT 
 if the context pointer is invalid
 .LP
+.B GETDNS_RETURN_INVALID PARAMETER 
+one or more parameters has an invalid value
+.LP
 .B GETDNS_RETURN_BAD_DOMAIN_NAME
 if the domain name passed to the function is invalid
 .LP
@@ -142,6 +138,10 @@ if the data type specified in one or more of the extensions does not match the s
 .LP
 .B GETDNS_RETURN_NO_SUCH_EXTENSION
 if one or more of the strings specified in the extensions are not valid
+.LP
+.B GETDNS_RETURN_GENERIC_ERROR
+some problem was encountered in the function not addressed by one of the more
+specific return codes
 
 The values of status included in the response parameter are:
 
@@ -260,8 +260,9 @@ TBD
 .BR getdns_address (3),
 .BR getdns_address_sync (3),
 .BR getdns_context (3),
+.BR getdns_free_sync_request_memory (3), 
 .BR getdns_hostname (3),
 .BR getdns_hostname_sync (3),
 .BR getdns_service (3),
-.BR getdns_service_sync (3).
+.BR getdns_service_sync (3)
 

doc/getdns_hostname.3.in

@@ -40,11 +40,11 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_hostname
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
-struct getdns_dict *address,
+getdns_dict *address,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
 void *userarg,
 .br
@@ -56,15 +56,13 @@ getdns_callback_t callbackfn)
 getdns_return_t 
 .br
 .B getdns_hostname_sync
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
-struct getdns_dict *address,
+getdns_dict *address,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
-uint32_t *response_length,
+getdns_dict **response)
-.br
-struct getdns_dict **response)
 .RE
 
 .SH DESCRIPTION
@@ -84,32 +82,27 @@ a getdns_dict structure containing two names: address_type (whose value is binda
 
 .HP 3
 .I extensions
-
+.RP
 extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
 
 .HP 3
 .I userarg
-
+.RP
 returned to the callback function untouched, can be NULL
 
 .HP 3
 .I transaction_id
-
+.RP
 populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails
 
 .HP 3
 .I callbackfn
-
+.RP
 pointer to a callback function defined by the application, typically used to process the response, may not be NULL. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback.
 
-.HP 3
-.I response_length
-
-The synchronous entry point includes this argument, the response length is placed at the address pointed to by response_length.
-
 .HP 3
 .I response
-
+.RP
 A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int).  The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3).
 
 .HP
@@ -123,6 +116,9 @@ Upon successful completion the functions return
 .B GETDNS_RETURN_BAD_CONTEXT 
 if the context pointer is invalid
 .LP
+.B GETDNS_RETURN_INVALID PARAMETER 
+one or more parameters has an invalid value
+.LP
 .B GETDNS_RETURN_BAD_DOMAIN_NAME
 if the domain name passed to the function is invalid
 .LP
@@ -131,6 +127,10 @@ if the data type specified in one or more of the extensions does not match the s
 .LP
 .B GETDNS_RETURN_NO_SUCH_EXTENSION
 if one or more of the strings specified in the extensions are not valid
+.LP
+.B GETDNS_RETURN_GENERIC_ERROR
+some problem was encountered in the function not addressed by one of the more
+specific return codes
 
 The values of status in the response include:
 
@@ -164,10 +164,12 @@ TBD
 
 .SH SEE ALSO
 .BR libgetdns (3),
+.BR getdns_context (3), 
+.BR getdns_free_sync_request_memory (3), 
 .BR getdns_general (3), 
 .BR getdns_general_sync (3), 
 .BR getdns_address (3), 
 .BR getdns_address_sync (3), 
 .BR getdns_service (3), 
-.BR getdns_service_sync (3).
+.BR getdns_service_sync (3)
 

doc/getdns_list.3.in

@@ -38,7 +38,7 @@ DNS Resolver library (libgetdns, -lgetdns)
 .SH SYNOPSIS
 #include <getdns.h>
 
-struct getdns_list * 
+getdns_list * 
 .br
 .B getdns_list_create
 ()
@@ -46,7 +46,7 @@ struct getdns_list *
 void 
 .br
 .B getdns_list_destroy
-(struct getdns_list *this_dict)
+(getdns_list *this_dict)
 
 .SH DESCRIPTION
 
@@ -54,11 +54,11 @@ void
 The getdns_list type is used to manage heterogeneous indexed lists name/value pairs in which the data types of the values include
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_list_get.3.in

@@ -45,32 +45,60 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_list_get_bindata
-(struct getdns_list *this_list, size_t index, struct getdns_bindata **answer)
+(getdns_list *this_list,
+.RS 3
+size_t index,
+.br
+getdns_bindata **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_get_data_type
-(struct getdns_list *this_list, size_t index, getdns_data_type *answer)
+(getdns_list *this_list,
+.RS 3
+size_t index,
+.br
+getdns_data_type *answer)
+.RE
 
 getdns_return_t
 .br
 .B getdns_list_get_dict
-(struct getdns_list *this_list, size_t index, struct getdns_dict **answer)
+(getdns_list *this_list,
+.RS 3
+size_t index,
+.br
+getdns_dict **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_get_length
-(struct getdns_list *this_list, size_t *answer)
+(getdns_list *this_list,
+.RS 3
+size_t *answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_get_list
-(struct getdns_list *this_list, size_t index, struct getdns_list **answer)
+(getdns_list *this_list,
+.RS 3
+size_t index,
+.br
+getdns_list **answer)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_get_int
-(struct getdns_list *this_list, size_t index, uint32_t *answer)
+(getdns_list *this_list,
+.RS 3
+size_t index,
+.br
+uint32_t *answer)
+.RE
 
 .SH DESCRIPTION
 
@@ -78,11 +106,11 @@ getdns_return_t
 The getdns_list type is used to manage heterogeneous lists in which the objects are each one of the data types:
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_list_set.3.in

@@ -43,22 +43,42 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_list_set_bindata
-(struct getdns_list *this_list, char *name, struct getdns_bindata *child_bindata)
+(getdns_list *this_list,
+.RS 3
+char *name,
+.br
+getdns_bindata *child_bindata)
+.RE
 
 getdns_return_t
 .br
 .B getdns_list_set_dict
-(struct getdns_list *this_list, char *name, struct getdns_dict *child_dict)
+(getdns_list *this_list,
+.RS 3
+char *name,
+.br
+getdns_dict *child_dict)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_set_int
-(struct getdns_list *this_list, char *name, uint32_t child_uint32_t)
+(getdns_list *this_list,
+.RS 3
+char *name,
+.br
+uint32_t child_uint32_t)
+.RE
 
 getdns_return_t 
 .br
 .B getdns_list_set_list
-(struct getdns_list *this_list, char *name, struct getdns_list *child_list)
+(getdns_list *this_list,
+.RS 3
+char *name,
+.br
+getdns_list *child_list)
+.RE
 
 .SH DESCRIPTION
 
@@ -66,11 +86,11 @@ getdns_return_t
 The getdns_list type is used to manage a heterogeneous indexed list of values that include:
 .RS 3
 .br
-struct getdns_bindata
+getdns_bindata
 .br
-struct getdns_dict
+getdns_dict
 .br
-struct getdns_list
+getdns_list
 .br
 uint32_t
 .RE

doc/getdns_service.3.in

@@ -40,11 +40,11 @@ DNS Resolver library (libgetdns, -lgetdns)
 getdns_return_t 
 .br
 .B getdns_service
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
 void *userarg,
 .br
@@ -56,15 +56,13 @@ getdns_callback_t callbackfn)
 getdns_return_t 
 .br
 .B getdns_service_sync
-(getdns_context_t context,
+(getdns_context *context,
 .RS 3
 const char *name,
 .br
-struct getdns_dict *extensions,
+getdns_dict *extensions,
 .br
-uint32_t *response_length,
+getdns_dict **response)
-.br
-struct getdns_dict **response)
 .RE
 
 .SH DESCRIPTION
@@ -74,42 +72,37 @@ The getdns_service (3) and getdns_service_sync functions provide public entry po
 
 .HP 3
 .I context
-
+.RP
 see getdns_context (3)
 
 .HP 3
 .I name
-
+.RP
 the service name to resolve
 
 .HP 3
 .I extensions
-
+.RP
 extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
 
 .HP 3
 .I userarg
-
+.RP
 returned to the callback function untouched, can be NULL
 
 .HP 3
 .I transaction_id
-
+.RP
 populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails
 
 .HP 3
 .I callbackfn
-
+.RP
 pointer to a callback function defined by the application, typically used to process the response, may not be NULL. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback.
 
-.HP 3
-.I response_length
-
-The synchronous entry point includes this argument, the response length is placed at the address pointed to by response_length.
-
 .HP 3
 .I response
-
+.RP
 A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int).  The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3).
 
 .HP
@@ -123,6 +116,9 @@ Upon successful completion the functions return
 .B GETDNS_RETURN_BAD_CONTEXT 
 if the context pointer is invalid
 .LP
+.B GETDNS_RETURN_INVALID PARAMETER 
+one or more parameters has an invalid value
+.LP
 .B GETDNS_RETURN_BAD_DOMAIN_NAME
 if the domain name passed to the function is invalid
 .LP
@@ -131,6 +127,10 @@ if the data type specified in one or more of the extensions does not match the s
 .LP
 .B GETDNS_RETURN_NO_SUCH_EXTENSION
 if one or more of the strings specified in the extensions are not valid
+.LP
+.B GETDNS_RETURN_GENERIC_ERROR
+some problem was encountered in the function not addressed by one of the more
+specific return codes
 
 The values of status in the response include:
 
@@ -164,10 +164,12 @@ TBD
 
 .SH SEE ALSO
 .BR libgetdns (3),
+.BR getdns_context (3),
+.BR getdns_free_sync_request_memory (3), 
 .BR getdns_general (3),
 .BR getdns_general_sync (3),
 .BR getdns_hostname (3),
 .BR getdns_hostname_sync (3),
 .BR getdns_address (3),
-.BR getdns_address_sync (3).
+.BR getdns_address_sync (3)
 

doc/libgetdns.3.in

@@ -88,6 +88,9 @@ a struct used to hold binary data defined as { size_t size; uint8_t *binary_stuf
 
 .SH ASYNCHRONOUS USE
 
+.LP
+TBD
+
 .SH SYNCHRONOUS USE
 
 .LP
@@ -335,7 +338,7 @@ getdns_context_t context,
 .br
 uint16_t callback_type,
 .br
-struct getdns_dict *response,
+getdns_dict *response,
 .br
 void *userarg,
 .br