From dcb3037f1be36e63521883a7307d1bfada56f109 Mon Sep 17 00:00:00 2001 From: Glen Wiley Date: Wed, 19 Feb 2014 18:18:52 -0500 Subject: [PATCH] more updates to man pages...even closer to being done --- doc/Makefile.in | 2 +- doc/getdns_address.3.in | 2 +- doc/getdns_cancel_callback.3.in | 2 +- doc/getdns_context.3.in | 4 +- doc/getdns_context_set.3.in | 85 ++++++++++++++++++- doc/getdns_convert.3.in | 102 +++++++++++++++++++++++ doc/getdns_dict.3.in | 4 +- doc/getdns_dict_get.3.in | 4 +- doc/getdns_dict_set.3.in | 4 +- doc/getdns_free_sync_request_memory.3.in | 2 +- doc/getdns_general.3.in | 4 +- doc/getdns_hostname.3.in | 2 +- doc/getdns_list.3.in | 4 +- doc/getdns_list_get.3.in | 4 +- doc/getdns_list_set.3.in | 4 +- doc/getdns_service.3.in | 2 +- doc/libgetdns.3.in | 5 +- 17 files changed, 208 insertions(+), 28 deletions(-) create mode 100644 doc/getdns_convert.3.in diff --git a/doc/Makefile.in b/doc/Makefile.in index a0253bc9..4d4f0013 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -21,7 +21,7 @@ VPATH = @srcdir@ EDITS=-e 's/@''version@/$(version)/g' 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_dict.3 getdns_dict_get.3 getdns_dict_set.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_service.3 +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_free_sync_request_memory.3 getdns_general.3 getdns_hostname.3 getdns_list.3 getdns_list_get.3 getdns_list_set.3 getdns_service.3 default: all diff --git a/doc/getdns_address.3.in b/doc/getdns_address.3.in index 7b68a82d..5050862a 100644 --- a/doc/getdns_address.3.in +++ b/doc/getdns_address.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/getdns_cancel_callback.3.in b/doc/getdns_cancel_callback.3.in index b5c30cb6..9296e438 100644 --- a/doc/getdns_cancel_callback.3.in +++ b/doc/getdns_cancel_callback.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/getdns_context.3.in b/doc/getdns_context.3.in index 80321ee0..3b79ff0d 100644 --- a/doc/getdns_context.3.in +++ b/doc/getdns_context.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -147,7 +147,7 @@ In calls to the getdns_create_context functions this parameter is used to return .HP 3 .I set_from_os .RP -If set_from_os is 0 then the caller must provide forwarding name servers if running in stub mode. If set_from_os is 1 then the system files are used to initialize the context. /etc/resolv.conf is used to populate forwarders when running as a stub resolver (only "nameserver" lines are recognized). If set_from_os is 1 /etc/hosts entries are preferred before resorting to a DNS query. Errors in the system files will not prevent the context form being contructed. +If set_from_os is 0 then the caller must provide forwarding name servers if running in stub mode. If set_from_os is 1 then the system files are used to initialize the context. /etc/resolv.conf is used to populate forwarders when running as a stub resolver (only "nameserver" lines are recognized). If set_from_os is 1 /etc/hosts entries are preferred before resorting to a DNS query. Errors in the system files will not prevent the context form being constructed. .HP 3 .I userarg diff --git a/doc/getdns_context_set.3.in b/doc/getdns_context_set.3.in index bedc885b..961df7e5 100644 --- a/doc/getdns_context_set.3.in +++ b/doc/getdns_context_set.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -28,8 +28,11 @@ .TH getdns_context_set 3 "@date@" "getdns @version@" getdns .SH NAME +.B getdns_context_set_append_name, .B getdns_context_set_context_update_callback, +.B getdns_context_set_dns_root_servers, .B getdns_context_set_dns_transport, +.B getdns_context_set_follow_redirects, .B getdns_context_set_limit_outstanding_queries, .B getdns_context_set_namespaces, .B getdns_context_set_resolution_type, @@ -51,6 +54,15 @@ getdns_return_t (*callback)(struct getdns_context *context, uint16_t changed_item)) .RE +getdns_return_t +.br +.B getdns_context_set_dns_root_servers +(getdns_context_t context, +.RS 3 +.br +getdns_list *root_addresses) +.RE + getdns_return_t .br .B getdns_context_set_dns_transport @@ -60,6 +72,15 @@ getdns_return_t uint16_t transport) .RE +getdns_return_t +.br +.B getdns_context_set_follow_redirects +(getdns_context_t context, +.RS 3 +.br +getdns_redirects_t followredir) +.RE + getdns_return_t .br .B getdns_context_set_limit_outstanding_queries @@ -101,6 +122,47 @@ uint16_t timeout) .LP These functions are used to manipulate a previously allocated and initialized context, see getdns_context (3) for more details on the functions used to allocate, initialized and destroy contexts and for a more detailed discussion of the getdns_context in general. +.LP +.B getdns_context_set_context_update_callback +sets a function that will be called if changes to the system files (for example /etc/resolv.conf and /etc/hosts). + +.LP +.B getdns_context_set_dns_transport +specifies the transport used for DNS lookups, the default is to use UDP and fall back to +TCP as needed. + +.LP +.B getdns_context_set_limit_outstanding_queries +specifies the maximum number of outstanding DNS queries, the API will queue queries +over this limit until current queries are answers and will then automatically issue +the queries on the queue. + +.LP +.B +getdns_context_set_dns_root_servers +provides an alternate set of addresses to use +to look up the top level domains. The default (if this function is not called) is the +list of IANA root servers (think of this as the root hints). + +.LP +.B +getdns_context_set_follow_redirects +specifies whether or not DNS queries follow redirects (CNAME and DNAME), the default +behavior is to follow redirects and return the eventual target. + +.LP +.B getdns_context_set_namespaces +sets the namespaces to be used by the resolver, the default is DNS and then local +files. Future implementations will support netbios, mdns, and nis. + +.LP +.B getdns_context_set_resolution_type +specifies whether DNS queries are performed with non-recursive lookups or as a stub resolver. + +.LP +.B getdns_context_set_timeout +specifies the number of milliseconds the API will wait for a response. + .HP 3 .I context .RP @@ -111,20 +173,35 @@ a previously allocated and initialized getdns_context .RP a callback function that will be called when changes are made to the system files (/etc/resolv.conf and /etc/hosts) for contexts created with set_from_os = 1. When this function is called the changed_item parameter indicates which item in the context has changed. +.HP 3 +.I root_addresses +.RP +This is a list of getdns_dict types that each identify a single root server to +use to look up top level domains. Each dictionary includes two names, +.I address_type +, a bindata containing the string "IPv4" or "IPv6" and +.I address_data +a bindata containing the IP address. + .HP 3 .I transport .RP may be one of GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP, GETDNS_CONTEXT_UDP_ONLY, GETDNS_CONTEXT_TCP_ONLY, GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need more information on what each of these means reread the mnemonic and take a guess ;) +.HP 3 +.I followredir +.RP +If set to GETDNS_REDIRECTS_FOLLOW (the default) then the eventual target of the redirect is returned. If set to GETDNS_REDIRECTS_DO_NOT_FOLLOW then the CNAME or DNAME is returned and NOT the eventual target. + .HP 3 .I limit .RP -the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeeded the API will queue queries and issue them as the number of outstanding queries drops. A value of 0 indicates that there is no limit. +the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeded the API will queue queries and issue them as the number of outstanding queries drops. A value of 0 indicates that there is no limit. .HP 3 .I namespaces .RP -The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other funtions. The values are GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS. +The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other functions. The values are GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS. .HP 3 .I restype @@ -134,7 +211,7 @@ can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_ST .HP 3 .I timeout .RP -the number of seconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error. +the number of milliseconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error. .HP .SH "RETURN VALUES" diff --git a/doc/getdns_convert.3.in b/doc/getdns_convert.3.in new file mode 100644 index 00000000..91d5c395 --- /dev/null +++ b/doc/getdns_convert.3.in @@ -0,0 +1,102 @@ +.\" 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 name of the 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_convert 3 "@date@" "getdns @version@" getdns +.SH NAME +.B getdns_convert, +.B getdns_convert_dns_name_to_fqdn, +.B getdns_convert_fqdn_to_dns_name + +.SH LIBRARY +DNS Resolver library (libgetdns, -lgetdns) + +.SH SYNOPSIS +#include + +getdns_return_t +.br +.B getdns_convert_dns_name_to_fqdn +(const getdns_bindata *dns_name_wire_fmt, +.br +.RS 3 +char **fqdn_as_string) +.RE + +getdns_return_t +.br +.B getdns_convert_fqdn_to_dns_name +(char *fqdn_as_string, +.br +.RS 3 +const getdns_bindata **dns_name_wire_fmt) +.RE + +.SH DESCRIPTION + +.LP +Names in DNS fields are stored in a fashion very different from the normal +presentation format normally used in applications. The DNS format is described +in the first paragraph in Section 3.1 of RFC 1035; the presentation format here +is a null-terminated string with interior dots. These helper functions only +work with names in the DNS format that are not compressed. They are useful for +converting domain names in the replies_tree to and from the FQDN presentation +format. + +getdns_convert_dns_name_to_fqdn() converts a domain name in DNS format to the +presentation format. For example, the hex sequence 03 77 77 77 07 65 78 61 6d +70 6c 65 03 63 6f 6d 00 would be converted to "www.example.com". +getdns_convert_fqdn_to_dns_name() does the reverse: it converts a +null-terminated string in FQDN format to bytes in DNS format. + +.HP 3 +.I dns_name_wire_fmt +.RP +The non-compressed DNS wire format name (per RFC 1035) in a bindata structure that +will be converted to/from an fqdn. In getdns_convert_fqdn_to_dns_name storage is +allocated using the system allocator (malloc) and must be freed by the caller. + +.HP 3 +.I fqdn_as_string +.RP +a null terminated string to be converted to/from non-compressed DNS wire format name (per RFC 1035). +In getdns_convert_dns_name_to_fqdn storage is +allocated using the system allocator (malloc) and must be freed by the caller. + +.HP +.SH "RETURN VALUES" + +Upon successful completion the function returns +.B GETDNS_RETURN_GOOD + +.SH EXAMPLES + +TBD + +.SH SEE ALSO +.BR libgetdns (3) + diff --git a/doc/getdns_dict.3.in b/doc/getdns_dict.3.in index 8847b684..19aac043 100644 --- a/doc/getdns_dict.3.in +++ b/doc/getdns_dict.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -51,7 +51,7 @@ void .SH DESCRIPTION .LP -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 heterogenous and include +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 diff --git a/doc/getdns_dict_get.3.in b/doc/getdns_dict_get.3.in index 566a34bf..f0f693fb 100644 --- a/doc/getdns_dict_get.3.in +++ b/doc/getdns_dict_get.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -75,7 +75,7 @@ getdns_return_t .SH DESCRIPTION .LP -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 heterogenous and include +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 diff --git a/doc/getdns_dict_set.3.in b/doc/getdns_dict_set.3.in index 27fea8fd..72b7df44 100644 --- a/doc/getdns_dict_set.3.in +++ b/doc/getdns_dict_set.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -63,7 +63,7 @@ getdns_return_t .SH DESCRIPTION .LP -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 heterogenous and include +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 diff --git a/doc/getdns_free_sync_request_memory.3.in b/doc/getdns_free_sync_request_memory.3.in index 168fe9e6..e387f570 100644 --- a/doc/getdns_free_sync_request_memory.3.in +++ b/doc/getdns_free_sync_request_memory.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/getdns_general.3.in b/doc/getdns_general.3.in index 2062138b..fbba996c 100644 --- a/doc/getdns_general.3.in +++ b/doc/getdns_general.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -165,7 +165,7 @@ For a more detailed explanation of the response object see .SH REQUEST TYPES -This is a list of the most common request types, a full list of request types in more detail is avalabile at http://www.iana.org/assignments/dns-parameters/dns-parameters.xml +This is a list of the most common request types, a full list of request types in more detail is available at http://www.iana.org/assignments/dns-parameters/dns-parameters.xml .RS 3 .TP 11 diff --git a/doc/getdns_hostname.3.in b/doc/getdns_hostname.3.in index 56a36221..08c81e02 100644 --- a/doc/getdns_hostname.3.in +++ b/doc/getdns_hostname.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/getdns_list.3.in b/doc/getdns_list.3.in index 3185b3b8..c72ac02e 100644 --- a/doc/getdns_list.3.in +++ b/doc/getdns_list.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -51,7 +51,7 @@ void .SH DESCRIPTION .LP -The getdns_list type is used to manage heterogenous indexed lists name/value pairs in which the data types of the values include +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 diff --git a/doc/getdns_list_get.3.in b/doc/getdns_list_get.3.in index f14d246e..90d5838a 100644 --- a/doc/getdns_list_get.3.in +++ b/doc/getdns_list_get.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -75,7 +75,7 @@ getdns_return_t .SH DESCRIPTION .LP -The getdns_list type is used to manage heterogenous lists in which the objects are each one of the data types: +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 diff --git a/doc/getdns_list_set.3.in b/doc/getdns_list_set.3.in index 1099547e..c72d3e03 100644 --- a/doc/getdns_list_set.3.in +++ b/doc/getdns_list_set.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -63,7 +63,7 @@ getdns_return_t .SH DESCRIPTION .LP -The getdns_list type is used to manage a heterogenous indexed list of values that include: +The getdns_list type is used to manage a heterogeneous indexed list of values that include: .RS 3 .br struct getdns_bindata diff --git a/doc/getdns_service.3.in b/doc/getdns_service.3.in index 33c4310d..f1183ad7 100644 --- a/doc/getdns_service.3.in +++ b/doc/getdns_service.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, NLNet Labs, Versign, Inc. +.\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without diff --git a/doc/libgetdns.3.in b/doc/libgetdns.3.in index fbbcfc5d..6dcd9d42 100644 --- a/doc/libgetdns.3.in +++ b/doc/libgetdns.3.in @@ -1,6 +1,6 @@ .\" The "BSD-New" License .\" -.\" Copyright (c) 2013, Versign, Inc. +.\" Copyright (c) 2013, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -357,7 +357,7 @@ Supplies the reason for the callback. The response has the requested data in it .LP .B GETDNS_CALLBACK_CANCEL -The calling program cancelled the callback; response is NULL +The calling program canceled the callback; response is NULL .LP .B GETDNS_CALLBACK_TIMEOUT The requested action timed out; response is NULL @@ -418,6 +418,7 @@ TBD .BR getdns_address (3), .BR getdns_bindata (3), .BR getdns_context (3), +.BR getdns_convert (3), .BR getdns_dict (3), .BR getdns_general (3), .BR getdns_hostname (3),