added dict/list memory functions, api_information, cleaned up copyrights

doc/Makefile.in

@@ -47,7 +47,7 @@ EDITS=-e 's/@''version@/$(version)/g'
 DOXYGEN = @DOXYGEN@
 
 DOCDIRS = html latex man
-MANPAGES3 = libgetdns.3 getdns_address.3 getdns_cancel_callback.3 getdns_context.3 getdns_context_create.3 getdns_context_set.3 getdns_convert.3 getdns_dict.3 getdns_dict_get.3 getdns_dict_set.3 getdns_display_ip_address.3 getdns_free_sync_request_memory.3 getdns_general.3 getdns_hostname.3 getdns_list.3 getdns_list_get.3 getdns_list_set.3 getdns_pretty_print_dict.3 getdns_root_trust_anchor.3 getdns_service.3 getdns_validate_dnssec.3 
+MANPAGES3 = libgetdns.3 getdns_address.3 getdns_cancel_callback.3 getdns_context.3 getdns_context_create.3 getdns_context_set.3 getdns_context_set_context_update_callback.3 getdns_convert.3 getdns_dict.3 getdns_dict_get.3 getdns_dict_set.3 getdns_display_ip_address.3 getdns_free_sync_request_memory.3 getdns_general.3 getdns_hostname.3 getdns_list.3 getdns_list_get.3 getdns_list_set.3 getdns_pretty_print_dict.3 getdns_root_trust_anchor.3 getdns_service.3 getdns_validate_dnssec.3 
 
 default: all
 

doc/getdns_cancel_callback.3.in

@@ -1,6 +1,6 @@
 .\" The "BSD-New" License
 .\" 
-.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc.
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
 .\" All rights reserved.
 .\" 
 .\" Redistribution and use in source and binary forms, with or without
@@ -72,9 +72,12 @@ Upon successful completion the functions return
 .B GETDNS_RETURN_GOOD
 , otherwise the following error values are returned:
 
+.LP
+.B GETDNS_RETURN_INVALID_PARAMETER
+if context == NULL
 .LP
 .B GETDNS_RETURN_UNKNOWN_TRANSACTION 
-when calling getdns_cancel_callback() with a transaction_id of a callback that has already been called or an unknown transaction_id
+if the transaction_id that is unknown or belongs to a callback that has already been called 
 
 .SH EXAMPLES
 

doc/getdns_context.3.in

@@ -1,6 +1,6 @@
 .\" The "BSD-New" License
 .\" 
-.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc.
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
 .\" All rights reserved.
 .\" 
 .\" Redistribution and use in source and binary forms, with or without
@@ -31,7 +31,8 @@
 .B getdns_context_create, 
 .B getdns_context_create_with_memory_functions, 
 .B getdns_context_create_with_extended_memory_functions, 
-.B getdns_context_destroy 
+.B getdns_context_destroy, 
+.B getdns_context_get_api_information 
 -- getdns context create and destroy routines
 
 .SH LIBRARY
@@ -86,6 +87,11 @@ void
 .B getdns_context_destroy
 (getdns_context *context)
 
+getdns_dict *
+.br
+.B getdns_context_get_api_information
+(getdns_context *context)
+
 .SH DESCRIPTION
 
 .LP
@@ -185,6 +191,22 @@ memory allocation failed or some other untoward thing happened while initializin
 .B GETDNS_RETURN_BAD_CONTEXT 
 if the context pointer is invalid (getdns_context_destroy)
 
+.LP
+The getdns_dict returned by gertdns_context_get_api_information must be
+destroyed by the called and includes the following name/value pairs:
+
+.IP version_string
+a bindata containing a printable string of the version of the DNS API implemented by this library
+
+.IP implementation_string
+a bindata containing a printable string set by the implementation
+
+.IP resolver_type
+an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB
+
+.IP all_context
+a getdns_dict with names for all the types of context, feed it to getdns_pretty_print_dict (3) for something easily readable
+
 .SH EXAMPLES
 
 TBD
@@ -200,6 +222,7 @@ TBD
 .BR getdns_address (3),
 .BR getdns_address_sync (3),
 .BR getdns_context_set (3),
+.BR getdns_context_set_context_update_callback (3),
 .BR getdns_general (3),
 .BR getdns_general_sync (3),
 .BR getdns_hostname (3),

doc/getdns_context_set_context_update_callback.3.in

@@ -0,0 +1,90 @@
+.\" The "BSD-New" License
+.\" 
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
+.\" All rights reserved.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\" * Redistributions of source code must retain the above copyright
+.\"   notice, this list of conditions and the following disclaimer.
+.\" * Redistributions in binary form must reproduce the above copyright
+.\"   notice, this list of conditions and the following disclaimer in the
+.\"   documentation and/or other materials provided with the distribution.
+.\" * Neither the names of the copyright holders nor the
+.\"   names of its contributors may be used to endorse or promote products
+.\"   derived from this software without specific prior written permission.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+.\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\" 
+
+.TH getdns_context_set_context_update_callback 3 "@date@" "getdns @version@" getdns
+.SH NAME
+.B getdns_context_set_context_update_callback 
+
+.SH LIBRARY
+DNS Resolver library (libgetdns, -lgetdns)
+
+.SH SYNOPSIS
+#include <getdns.h>
+
+getdns_return_t
+.br
+.B getdns_context_set_context_update_callback
+(getdns_context ** context,
+.RS 3
+.br
+void (*cbfun)(getdns_context *context, getdns_context_code_t changed_item)
+.RE
+
+.SH DESCRIPTION
+
+.LP
+Changes to the context such as in response to system files that affect the contet (/etc/resolv.conf etc.) trigger a call to the callback function specified as
+.b
+cbfun
+
+.HP 3
+.I context
+.RP
+a previously initialized context
+
+.HP 3
+.I cbfun
+.RP
+callback function to invoked when the specified context changes.  If this 
+argument is NULL then updates to the context will not invoke a callback.
+
+.HP
+.SH "RETURN VALUES"
+
+Upon successful completion each of these functions return
+.B GETDNS_RETURN_GOOD
+, otherwise the following error values are returned:
+
+.LP
+.B GETDNS_RETURN_GENERIC_ERROR
+memory allocation failed or some other untoward thing happened 
+
+.LP
+.B GETDNS_RETURN_BAD_CONTEXT 
+if the context pointer is invalid
+
+.SH EXAMPLES
+
+TBD
+
+.SH SEE ALSO
+.BR libgetdns (3),
+.BR getdns_context_create (3),
+.BR getdns_context_set (3),
+.BR getdns_context_set_context_update_callback (3),
+

doc/getdns_dict.3.in

@@ -30,6 +30,8 @@
 .SH NAME
 .B getdns_dict, 
 .B getdns_dict_create, 
+.B getdns_dict_create_with_extended_memory_functions, 
+.B getdns_dict_create_with_memory_functions, 
 .B getdns_dict_destroy 
 
 .SH LIBRARY
@@ -43,6 +45,30 @@ getdns_dict *
 .B getdns_dict_create
 ()
 
+getdns_dict *
+.br
+.B getdns_dict_create_with_extended_memory_functions
+.RS 3
+(void *userarg,
+.br
+void *(*malloc)(void *userarg, size_t sz),
+.br
+void *(*realloc)(void *userarg, void *buf, size_t sz),
+.br
+void (*free)(void *userarg, void *buf)
+.RE 3
+
+getdns_dict *
+.br
+.B getdns_dict_create_with_memory_functions
+.RS 3
+(void *(*malloc)(size_t sz),
+.br
+void *(*realloc)(void *buf, size_t sz),
+.br
+void (*free)(void *buf)
+.RE 3
+
 void 
 .br
 .B getdns_dict_destroy
@@ -68,15 +94,19 @@ The destroy function performs a "deep" destroy, freeing storage for all of the m
 of the dictionary before destroying the dictionary.  There are a number of helper
 functions that provide access to the dictionary object, see their respective man pages.
 
+.LP
+.I userarg
+pass this argument to the user specified memory management functions for operations on lists created using extended memory functions 
 .LP
 .I this_dict
 the dictionary to destroy
-.LP
 
 .SH "RETURN VALUES"
 
-Upon successful completion the getdns_dict_create function returns a valid (empty) 
+Upon successful completion the getdns_dict_create function returns a valid
-dictionary structure that should be freed via a call to getdns_dict_destroy.
+(empty) dictionary structure that should be freed via a call to
+getdns_dict_destroy.  If a parameter in invalid or in the event of some error
+getdns_dict_create returns NULL.
 
 .SH EXAMPLES
 

doc/getdns_general.3.in

@@ -1,6 +1,6 @@
 .\" The "BSD-New" License
 .\" 
-.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc.
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
 .\" All rights reserved.
 .\" 
 .\" Redistribution and use in source and binary forms, with or without

doc/getdns_list.3.in

@@ -1,6 +1,6 @@
 .\" The "BSD-New" License
 .\" 
-.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc.
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
 .\" All rights reserved.
 .\" 
 .\" Redistribution and use in source and binary forms, with or without
@@ -30,6 +30,8 @@
 .SH NAME
 .B getdns_list, 
 .B getdns_list_create, 
+.B getdns_list_create_with_extended_memory_functions, 
+.B getdns_list_create_with_memory_functions, 
 .B getdns_list_destroy 
 
 .SH LIBRARY
@@ -43,6 +45,32 @@ getdns_list *
 .B getdns_list_create
 ()
 
+getdns_list *
+.br
+.B getdns_list_create_with_extended_memory_functions
+.RS 3
+(void *userarg,
+.br
+void *(*malloc)(void *userarg, size_t sz),
+.br
+void *(*realloc)(void *userarg, void *buf, size_t sz),
+.br
+void (*free)(void *userarg, void *buf)
+.RE 3
+
+getdns_list *
+.br
+.B getdns_list_create_with_memory_functions
+.RS 3
+(void *userarg,
+.br
+void *(*malloc)(size_t sz),
+.br
+void *(*realloc)(void *buf, size_t sz),
+.br
+void (*free)(void *buf)
+.RE 3
+
 void 
 .br
 .B getdns_list_destroy
@@ -68,15 +96,18 @@ The destroy function performs a "deep" destroy, freeing storage for all of the m
 of the list before destroying the list.  There are a number of helper
 functions that provide access to the list object, see their respective man pages.
 
+.LP
+.I userarg
+pass this argument to the user specified memory management functions for operations on lists created using extended memory functions 
+
 .LP
 .I this_list
 the list to destroy
-.LP
 
 .SH "RETURN VALUES"
 
 Upon successful completion the getdns_list_create function returns a valid (empty) 
-list structure that should be freed via a call to getdns_list_destroy.
+list structure that should be freed via a call to getdns_list_destroy.  If a parameter in invalid or in the event of some error getdns_list_create returns NULL.
 
 .SH EXAMPLES
 

doc/libgetdns.3.in

@@ -1,6 +1,6 @@
 .\" The "BSD-New" License
 .\" 
-.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc.
+.\" Copyright (c) 2013, NLnet Labs, Verisign, Inc.
 .\" All rights reserved.
 .\" 
 .\" Redistribution and use in source and binary forms, with or without

doc/manpgaltnames

@@ -2,7 +2,7 @@
 # generate list of alternate names for the specified man page
 # used to generate alternative man pages
 #
-# Copyright (c) 2013, Verisign, Inc., NLNet Labs
+# Copyright (c) 2013, Verisign, Inc., NLnet Labs
 # All rights reserved.
 # 
 # Redistribution and use in source and binary forms, with or without