mirror of https://github.com/getdnsapi/getdns.git
added text to man pages - still need some work but getting there
This commit is contained in:
Glen Wiley
parent
9c003c8963
commit
668e493d9b
|
|
@ -1,6 +1,36 @@
|
|||
.TH libgetdns 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, NLNet Labs, Versign, 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 <organization> 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_address 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
getdns_address
|
||||
.B getdns_address,
|
||||
.B getdns_address_sync
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
|
|
@ -10,15 +40,121 @@ DNS Resolver library (libgetdns, -lgetdns)
|
|||
getdns_return_t
|
||||
.br
|
||||
.B getdns_address
|
||||
(getdns_context_t context, const char *name, struct getdns_dict *extensions, void *userarg, getdns_transaction_t *transaction_id, getdns_callback_t callbackfn);
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
void *userarg,
|
||||
.br
|
||||
getdns_transaction_t *transaction_id,
|
||||
.br
|
||||
getdns_callback_t callbackfn)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_address_sync
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
uint32_t *response_length,
|
||||
.br
|
||||
struct getdns_dict **response)
|
||||
.RE
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
THIS IS A WORK IN PROGRESS - MUCH TO ADD
|
||||
The getdns_address(3) and getdns_address_sync functions provide public entry points into the getdns API library to retrieve the address given a host name. It always returns both IPv4 and IPv6 addresses.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
|
||||
the host name to resolve to an address (note that an IP address is considered invalid)
|
||||
|
||||
.HP 3
|
||||
.I extensions
|
||||
|
||||
extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
.SH "RETURN VALUES"
|
||||
|
||||
Upon successful completion the functions return
|
||||
.B GETDNS_RETURN_GOOD
|
||||
, otherwise the following error values are returned:
|
||||
|
||||
.LP
|
||||
The getdns_address(3) and getdns_address_sync functions provide public entry points into the getdns API library to retrieve the address given a host name. It always returns both IPv4 and IPv6 addresses.
|
||||
.B GETDNS_RETURN_BAD_CONTEXT
|
||||
if the context pointer is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_DOMAIN_NAME
|
||||
if the domain name passed to the function is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_EXTENSION_MISFORMAT
|
||||
if the data type specified in one or more of the extensions does not match the specifications
|
||||
.LP
|
||||
.B GETDNS_RETURN_NO_SUCH_EXTENSION
|
||||
if one or more of the strings specified in the extensions are not valid
|
||||
|
||||
The values of status in the response include:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
At least one response was returned
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_NAME
|
||||
Queries for the name yielded all negative responses
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_ALL_TIMEOUT
|
||||
All queries for the name timed out
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
|
||||
only secure replies accepted (per context), at least one response was received but no DNS responses were secure through DNSSEC
|
||||
|
||||
.LP
|
||||
For a more detailed explanation of the response object see
|
||||
.I libgetdns
|
||||
(3)
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH FILES
|
||||
.br
|
||||
|
|
@ -26,17 +162,8 @@ The getdns_address(3) and getdns_address_sync functions provide public entry poi
|
|||
.br
|
||||
/etc/resolv.conf
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
TBD
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (3),
|
||||
.BR getdns_address_sync (3),
|
||||
.BR getdns_general (3),
|
||||
.BR getdns_general_sync (3),
|
||||
.BR getdns_hostname (3),
|
||||
|
|
|
|||
|
|
@ -0,0 +1,97 @@
|
|||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, Versign, 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 <organization> 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_dict 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
.B getdns_dict,
|
||||
.B getdns_dict_get_names,
|
||||
.B getdns_dict_get_data_type,
|
||||
.B getdns_dict_get_dict,
|
||||
.B getdns_dict_get_list,
|
||||
.B getdns_dict_get_int
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
#include <getdns.h>
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_dict_get_names
|
||||
(struct getdns_dict *this_dict, struct getdns_list **answer)
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
THIS IS A WORK IN PROGRESS - MUCH TO ADD
|
||||
|
||||
.LP
|
||||
The getdns_dict type is used to manage name/value pairs in which the data types of the values are heterogenous and include
|
||||
.RS 3
|
||||
.br
|
||||
struct getdns_bindata
|
||||
.br
|
||||
struct getdns_dict
|
||||
.br
|
||||
struct getdns_list
|
||||
.br
|
||||
uint32_t
|
||||
.RE
|
||||
|
||||
.LP
|
||||
.I this_dict
|
||||
the dictionary from which to retrieve the list of names
|
||||
.LP
|
||||
.I answer
|
||||
the list of all names in the dictionary, note that the caller must free storage allocated to the list via a call to
|
||||
.B getdns_list_destroy(3)
|
||||
|
||||
.SH "RETURN VALUES"
|
||||
|
||||
Upon successful completion the functions return
|
||||
.B GETDNS_RETURN_GOOD
|
||||
, otherwise the following error values are returned:
|
||||
.LP
|
||||
.B GETDNS_RETURN_GENERIC_ERROR
|
||||
if this_dict is not a valid dictionary
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (3),
|
||||
.BR getdns_general (3),
|
||||
.BR getdns_general_sync (3),
|
||||
.BR getdns_hostname (3),
|
||||
.BR getdns_hostname_sync (3),
|
||||
.BR getdns_list (3),
|
||||
.BR getdns_service (3),
|
||||
.BR getdns_service_sync (3).
|
||||
|
||||
|
|
@ -0,0 +1,267 @@
|
|||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, NLNet Labs, Versign, 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 <organization> 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_general 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
.B getdns_general,
|
||||
.B getdns_general_sync
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
#include <getdns.h>
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_general
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
uint16_t request_type
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
void *userarg,
|
||||
.br
|
||||
getdns_transaction_t *transaction_id,
|
||||
.br
|
||||
getdns_callback_t callbackfn)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_general_sync
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
uint16_t request_type
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
uint32_t *response_length,
|
||||
.br
|
||||
struct getdns_dict **response)
|
||||
.RE
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
The getdns_general(3) and getdns_general_sync functions provide public entry points into the getdns API library to retrieve any valid responses to a query from the DNS.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
|
||||
The ASCII-based domain name looked up as a string. This can also be an
|
||||
IPv4 or IPv6 address for request types that take addresses instead of domain
|
||||
names, such as PTR. The values here follow the rules in section 2.1 of RFC 4343
|
||||
to allow non-ASCII octets and special characters in labels.
|
||||
|
||||
.HP 3
|
||||
.I request_type
|
||||
|
||||
Specifies the RRtype for the query; the RRtype numbers are listed in the IANA registry. For example, to get the NS records, request_type would be 2. The API also has defined macros for most of the RRtypes by name; the definition names all start with "GETDNS_RRTYPE_". For example, to get the NS records, you can also set the request_type to GETDNS_RRTYPE_NS.
|
||||
|
||||
.HP 3
|
||||
.I extensions
|
||||
|
||||
extensions for this request, NULL if no extensions, see libgetnds (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
.SH "RETURN VALUES"
|
||||
|
||||
Upon successful completion the functions return
|
||||
.B GETDNS_RETURN_GOOD
|
||||
, otherwise the following error values are returned:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_CONTEXT
|
||||
if the context pointer is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_DOMAIN_NAME
|
||||
if the domain name passed to the function is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_EXTENSION_MISFORMAT
|
||||
if the data type specified in one or more of the extensions does not match the specifications
|
||||
.LP
|
||||
.B GETDNS_RETURN_NO_SUCH_EXTENSION
|
||||
if one or more of the strings specified in the extensions are not valid
|
||||
|
||||
The values of status in the response include:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
At least one response was returned
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_NAME
|
||||
Queries for the name yielded all negative responses
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_ALL_TIMEOUT
|
||||
All queries for the name timed out
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
|
||||
only secure replies accepted (per context), at least one response was received but no DNS responses were secure through DNSSEC
|
||||
|
||||
.LP
|
||||
For a more detailed explanation of the response object see
|
||||
.I libgetdns
|
||||
(3)
|
||||
|
||||
.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
|
||||
|
||||
.RS 3
|
||||
.TP 11
|
||||
.B A
|
||||
Host address
|
||||
.TP
|
||||
.B AAAA
|
||||
IPv6 address
|
||||
.TP
|
||||
.B CNAME
|
||||
Canonical name for an alias
|
||||
.TP
|
||||
.B DLV
|
||||
DNSSEC lookaside validation
|
||||
.TP
|
||||
.B DNAME
|
||||
DNAME
|
||||
.TP
|
||||
.B DS
|
||||
Delegation signer
|
||||
.TP
|
||||
.B HINFO
|
||||
Host information
|
||||
.TP
|
||||
.B KEY
|
||||
Security key
|
||||
.TP
|
||||
.B MINFO
|
||||
Mailbox or mail list information
|
||||
.TP
|
||||
.B MX
|
||||
Mail exchange
|
||||
.TP
|
||||
.B NS
|
||||
Authoritative name server
|
||||
.TP
|
||||
.B NSEC
|
||||
NSEC
|
||||
.TP
|
||||
.B NSEC3
|
||||
NSEC3
|
||||
.TP
|
||||
.B NSEC3PARAM
|
||||
NSEC3PARAM
|
||||
.TP
|
||||
.B OPT
|
||||
OPT
|
||||
.TP
|
||||
.B PTR
|
||||
Domain name pointer
|
||||
.TP
|
||||
.B RRSIG
|
||||
RRSIG
|
||||
.TP
|
||||
.B SIG
|
||||
Security signature
|
||||
.TP
|
||||
.B SOA
|
||||
Marks the start of a zone of authority
|
||||
.TP
|
||||
.B SRV
|
||||
Server selection
|
||||
.TP
|
||||
.B TA
|
||||
DNSSEC trust authorities
|
||||
.TP
|
||||
.B TKEY
|
||||
Transaction key
|
||||
.TP
|
||||
.B TLSA
|
||||
TLSA
|
||||
.TP
|
||||
.B TSIG
|
||||
Transaction signature
|
||||
.TP
|
||||
.B TXT
|
||||
Text strings
|
||||
.RE
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH FILES
|
||||
.br
|
||||
/etc/hosts
|
||||
.br
|
||||
/etc/resolv.conf
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (3),
|
||||
.BR getdns_address (3),
|
||||
.BR getdns_address_sync (3),
|
||||
.BR getdns_hostname (3),
|
||||
.BR getdns_hostname_sync (3),
|
||||
.BR getdns_service (3),
|
||||
.BR getdns_service_sync (3).
|
||||
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, NLNet Labs, Versign, 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 <organization> 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_hostname 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
.B getdns_hostname,
|
||||
.B getdns_hostname_sync
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
#include <getdns.h>
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_hostname
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
struct getdns_dict *address,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
void *userarg,
|
||||
.br
|
||||
getdns_transaction_t *transaction_id,
|
||||
.br
|
||||
getdns_callback_t callbackfn)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_hostname_sync
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
struct getdns_dict *address,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
uint32_t *response_length,
|
||||
.br
|
||||
struct getdns_dict **response)
|
||||
.RE
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
The getdns_hostname(3) and getdns_hostname_sync functions provide public entry points into the getdns API library to retrieve the host name given an address.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I address
|
||||
|
||||
a getdns_dict structure containing two names: address_type (whose value is bindata and is either "IPv4" or "IPv6") and address_data whose value is bindata
|
||||
|
||||
.HP 3
|
||||
.I extensions
|
||||
|
||||
extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
.SH "RETURN VALUES"
|
||||
|
||||
Upon successful completion the functions return
|
||||
.B GETDNS_RETURN_GOOD
|
||||
, otherwise the following error values are returned:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_CONTEXT
|
||||
if the context pointer is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_DOMAIN_NAME
|
||||
if the domain name passed to the function is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_EXTENSION_MISFORMAT
|
||||
if the data type specified in one or more of the extensions does not match the specifications
|
||||
.LP
|
||||
.B GETDNS_RETURN_NO_SUCH_EXTENSION
|
||||
if one or more of the strings specified in the extensions are not valid
|
||||
|
||||
The values of status in the response include:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
At least one response was returned
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_NAME
|
||||
Queries for the name yielded all negative responses
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_ALL_TIMEOUT
|
||||
All queries for the name timed out
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
|
||||
only secure replies accepted (per context), at least one response was received but no DNS responses were secure through DNSSEC
|
||||
|
||||
.LP
|
||||
For a more detailed explanation of the response object see
|
||||
.I libgetdns
|
||||
(3)
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH FILES
|
||||
.br
|
||||
/etc/hosts
|
||||
.br
|
||||
/etc/resolv.conf
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (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).
|
||||
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, NLNet Labs, Versign, 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 <organization> 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_service 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
.B getdns_service,
|
||||
.B getdns_service_sync
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
#include <getdns.h>
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_service
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
void *userarg,
|
||||
.br
|
||||
getdns_transaction_t *transaction_id,
|
||||
.br
|
||||
getdns_callback_t callbackfn)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_service_sync
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
const char *name,
|
||||
.br
|
||||
struct getdns_dict *extensions,
|
||||
.br
|
||||
uint32_t *response_length,
|
||||
.br
|
||||
struct getdns_dict **response)
|
||||
.RE
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
The getdns_service (3) and getdns_service_sync functions provide public entry points into the getdns API library to retrieve the SRV information given a name.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
|
||||
the service name to resolve
|
||||
|
||||
.HP 3
|
||||
.I extensions
|
||||
|
||||
extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
.SH "RETURN VALUES"
|
||||
|
||||
Upon successful completion the functions return
|
||||
.B GETDNS_RETURN_GOOD
|
||||
, otherwise the following error values are returned:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_CONTEXT
|
||||
if the context pointer is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_DOMAIN_NAME
|
||||
if the domain name passed to the function is invalid
|
||||
.LP
|
||||
.B GETDNS_RETURN_EXTENSION_MISFORMAT
|
||||
if the data type specified in one or more of the extensions does not match the specifications
|
||||
.LP
|
||||
.B GETDNS_RETURN_NO_SUCH_EXTENSION
|
||||
if one or more of the strings specified in the extensions are not valid
|
||||
|
||||
The values of status in the response include:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
At least one response was returned
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_NAME
|
||||
Queries for the name yielded all negative responses
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_ALL_TIMEOUT
|
||||
All queries for the name timed out
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
|
||||
only secure replies accepted (per context), at least one response was received but no DNS responses were secure through DNSSEC
|
||||
|
||||
.LP
|
||||
For a more detailed explanation of the response object see
|
||||
.I libgetdns
|
||||
(3)
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
TBD
|
||||
|
||||
.SH FILES
|
||||
.br
|
||||
/etc/hosts
|
||||
.br
|
||||
/etc/resolv.conf
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (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).
|
||||
|
||||
|
|
@ -1,3 +1,31 @@
|
|||
.\" The "BSD-New" License
|
||||
.\"
|
||||
.\" Copyright (c) 2013, Versign, 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 <organization> 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 libgetdns 3 "November 2013" "getdns 0.0.0" getdns
|
||||
.SH NAME
|
||||
libgetdns
|
||||
|
|
@ -6,17 +34,13 @@ DNS Resolver library (libgetdns, -lgetdns)
|
|||
|
||||
.SH SYNOPSIS
|
||||
.Lb libgetdns
|
||||
#include <getdns.h>
|
||||
|
||||
THe public entry points are captured in separate man pages.
|
||||
This man page describes the getdns library, the general concepts behind the API and some of the common elements of the public interface to the library. Each of the public entry points and more complex data types are captured in separate man pages.
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
THIS IS A WORK IN PROGRESS - LOTS TO ADD
|
||||
|
||||
.LP
|
||||
This document describes a modern asynchronous DNS API. This new API is intended to be useful to application developers and operating system distributors as a way of making all types of DNS information easily available in many types of programs. The major features of this new API are:
|
||||
getdns is modern asynchronous DNS API intended to be useful to application developers and operating system distributors as a way of making all types of DNS information easily available in many types of programs. The major features of this new API are:
|
||||
|
||||
.RS 3
|
||||
Full support for event-driven programming
|
||||
|
|
@ -25,9 +49,225 @@ This document describes a modern asynchronous DNS API. This new API is intended
|
|||
Easily supports all RRtypes, even those yet to be defined
|
||||
.RE
|
||||
|
||||
.LP
|
||||
Each of the entry points is offered with both asynchronous and synchronous signatures. The asynchronous functions rely on event handling and callback via libevent.
|
||||
Functions are thread safe.
|
||||
|
||||
.LP
|
||||
A context structure maintains DNS query and response data and is used to maintain state during calls to the public entry points.
|
||||
|
||||
.SH EXTENSIONS
|
||||
|
||||
Applications may populate an extension dictionary when making a call to the public entry points. To use an extension add it to the extension dictionary prior to making the call to the public entry point and set the value depending on the behavior you expect. These extensions include:
|
||||
|
||||
.HP 3
|
||||
dnssec_return_status (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each DNS record in the replies_tree
|
||||
|
||||
.HP 3
|
||||
dnssec_return_only_secure (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure withe DNSSEC to be returned in the
|
||||
.I replies_tree
|
||||
and
|
||||
.I replies_full lists
|
||||
|
||||
.HP 3
|
||||
dnssec_return_supporting_responses (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to cause the set of additional DNSSEC-related records needed for validation to be returned in the response object as the list named
|
||||
.I additional_dnssec
|
||||
at the top level of the response object
|
||||
|
||||
.HP 3
|
||||
return_both_v4_and_v6 (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to cause the results of both A and AAAA records for the queried name to be included in the response object.
|
||||
|
||||
.HP 3
|
||||
add_opt_parameters (dict)
|
||||
|
||||
TBD (complicated)
|
||||
|
||||
.HP 3
|
||||
add_warning_for_bad_dns
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to cause each reply in the
|
||||
.I replies_tree
|
||||
to contain an additional name whose data type is a list,
|
||||
.I bad_dns
|
||||
which contains zero or more ints that indicate the types of bad DNS found in the reply.
|
||||
.RS 6
|
||||
.br
|
||||
GETDNS_BAD_DNS_CNAME_IN_TARGET: query type does not allow a CNAME pointed to a CNAME
|
||||
.br
|
||||
GETDNS_BAD_DNS_ALL_NUMERIC_LABEL: one or more labels is all numeric
|
||||
.br
|
||||
GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE: query type for other than CNAME returned a CNAME
|
||||
.RE
|
||||
|
||||
.HP 3
|
||||
specify_class (int)
|
||||
|
||||
Set to the DNS class number (other than Internet (IN) class desired in query.
|
||||
|
||||
.HP 3
|
||||
return_api_information (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to add the following to the top level of the response object:
|
||||
.RS 6
|
||||
.br
|
||||
.I version_string
|
||||
(bindata) : the version string for this version of the getdns API
|
||||
.br
|
||||
.I implementation_string
|
||||
(bindata) : string set by this library's implementer as a build or version indicator
|
||||
.br
|
||||
.I resolver_type
|
||||
(int) : GETDNS_CONTEXT_RECURSING or GETDNS_CONTEXT_STUB depending on how the context is configured
|
||||
.br
|
||||
.I all_context
|
||||
(dict) : includes names from the context, use with
|
||||
.I getdns_pretty_print_dict
|
||||
(3) for debugging
|
||||
.RE
|
||||
|
||||
.HP 3
|
||||
return_call_debugging (int)
|
||||
|
||||
Set to GETDNS_EXTENSION_TRUE to add the name
|
||||
.I call_debugging
|
||||
(list) to the top level of the response object that includes a dict for each call made to the API. TBD: more detail
|
||||
|
||||
.LP
|
||||
This implementation of the getdns API is licensed under the BSD license.
|
||||
|
||||
.SH Response Data from Queries
|
||||
|
||||
.LP
|
||||
The callback function contains a pointer to a response object. A response
|
||||
object is always a dict. The response object always contains at least three
|
||||
names: replies_full (a list) and replies_tree (a list), and status (an int).
|
||||
replies_full is a list of DNS replies (each is bindata) as they appear on the
|
||||
wire. replies_tree is a list of DNS replies (each is a dict) with the various
|
||||
part of the reply parsed out. status is a status code for the query.
|
||||
|
||||
.LP
|
||||
Because the API might be extended in the future, a response object might also
|
||||
contain names other than replies_full, replies_tree, and status. Similarly, any
|
||||
of the dicts described here might be extended in later versions of the API.
|
||||
Thus, an application using the API must not assume that it knows all possible
|
||||
names in a dict.
|
||||
|
||||
.LP
|
||||
The following lists the status codes for response objects. Note that, if the
|
||||
status is that there are no responses for the query, the lists in replies_full
|
||||
and replies_tree will have zero length.
|
||||
|
||||
.HP 3
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
At least one response was returned
|
||||
.HP 3
|
||||
.B GETDNS_RESPSTATUS_NO_NAME
|
||||
Queries for the name yielded all negative responses
|
||||
.HP 3
|
||||
.B GETDNS_RESPSTATUS_ALL_TIMEOUT
|
||||
All queries for the name timed out
|
||||
.HP 3
|
||||
.B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS
|
||||
The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC.
|
||||
|
||||
.LP
|
||||
The top level of replies_tree can optionally have the following names: canonical_name (a bindata), intermediate_aliases (a list), answer_ipv4_address (a bindata), answer_ipv6_address (a bindata), and answer_type (an int).
|
||||
|
||||
.LP
|
||||
The value of canonical_name is the name that the API used for its lookup. It is
|
||||
in FQDN presentation format. The values in the intermediate_aliases list are
|
||||
domain names from any CNAME or unsynthesized DNAME found when resolving the
|
||||
original query. The list might have zero entries if there were no CNAMEs in the
|
||||
path. These may be useful, for example, for name comparisons when following the
|
||||
rules in RFC 6125. The value of answer_ipv4_address and answer_ipv6_address
|
||||
are the addresses of the server from which the answer was received. The value
|
||||
of answer_type is the type of name service that generated the response. The
|
||||
values are:
|
||||
|
||||
.RS 3
|
||||
GETDNS_NAMETYPE_DNS
|
||||
Normal DNS (RFC 1035)
|
||||
GETDNS_NAMETYPE_WINS
|
||||
The WINS name service (some reference needed)
|
||||
.RE
|
||||
|
||||
.LP
|
||||
If the call was getdns_address or getdns_address_sync, the top level of
|
||||
replies_tree has an additional name, just_address_answers (a list). The value
|
||||
of just_address_answers is a list that contains all of the A and AAAA records
|
||||
from the answer sections of any of the replies, in the order they appear in the
|
||||
replies. Each item in the list is a dict with at least two names: address_type
|
||||
(whose value is a bindata; it is currently either "IPv4" or "IPv6") and
|
||||
address_data (whose value is a bindata). Note that the
|
||||
dnssec_return_only_secure extension affects what will appear in the
|
||||
just_address_answers list. If the DNS returns other
|
||||
address types, those types will appear in this list as well.
|
||||
|
||||
.LP
|
||||
The API can make service discovery through SRV records easier. If the call was
|
||||
getdns_service or getdns_service_sync, the top level of replies_tree has an
|
||||
additional name, srv_addresses (a list). The list is ordered by priority and
|
||||
weight based on the weighting algorithm in RFC 2782, lowest priority value
|
||||
first. Each element of the list is dict has at least two names: port and
|
||||
domain_name. If the API was able to determine the address of the target domain
|
||||
name (such as from its cache or from the Additional section of responses), the
|
||||
dict for an element will also contain address_type (whose value is a bindata;
|
||||
it is currently either "IPv4" or "IPv6") and address_data (whose value is a
|
||||
bindata). Note that the dnssec_return_only_secure extension affects what will
|
||||
appear in the srv_addresses list.
|
||||
|
||||
.SH Structure of DNS replies_tree
|
||||
|
||||
.LP
|
||||
The names in each entry in the the replies_tree list for DNS responses include
|
||||
header (a dict), question (a dict), answer (a list), authority (a list), and
|
||||
additional (a list), corresponding to the sections in the DNS message format.
|
||||
The answer, authority, and additional lists each contain zero or more dicts,
|
||||
with each dict in each list representing a resource record.
|
||||
|
||||
.LP
|
||||
The names in the header dict are all the fields from Section 4.1.1. of RFC
|
||||
1035. They are: id, qr, opcode, aa, tc, rd, ra, z, rcode, qdcount, ancount,
|
||||
nscount, and arcount. All are ints.
|
||||
|
||||
.LP
|
||||
The names in the question dict are the three fields from Section 4.1.2. of RFC
|
||||
1035: qname (a bindata), qtype (an int), and qclass (an int).
|
||||
|
||||
.LP
|
||||
Resource records are a bit different than headers and question sections in that
|
||||
the RDATA portion often has its own structure. The other names in the resource
|
||||
record dicts are name (a bindata), type (an int), class (an int), ttl (an int)
|
||||
and rdata (a dict); there is no name equivalent to the RDLENGTH field.
|
||||
|
||||
.LP
|
||||
The rdata dict has different names for each response type. There is a complete
|
||||
list of the types defined in the API. For names that end in "-obsolete" or
|
||||
"-unknown", the bindata is the entire RDATA field. For example, the rdata for
|
||||
an A record has a name ipv4_address (a bindata); the rdata for an SRV record
|
||||
has the names priority (an int), weight (an int), port (an int), and target (a
|
||||
bindata).
|
||||
|
||||
.LP
|
||||
Each rdata dict also has a rdata_raw field (a bindata). This is useful for
|
||||
types not defined in this version of the API. It also might be of value if a
|
||||
later version of the API allows for additional parsers. Thus, doing a query for
|
||||
types not known by the API still will return a result: an rdata with just a
|
||||
rdata_raw.
|
||||
|
||||
.LP
|
||||
It is expected that later extensions to the API will give some DNS types
|
||||
different names. It is also possible that later extensions will change the
|
||||
names for some of the DNS types listed above.
|
||||
|
||||
.SH FILES
|
||||
.br /etc/hosts
|
||||
.br /etc/resolv.conf
|
||||
|
|
@ -41,10 +281,13 @@ TBD
|
|||
.SH "SEE ALSO"
|
||||
.BR getdns_address (3),
|
||||
.BR getdns_address_sync (3),
|
||||
.BR getdns_context (3),
|
||||
.BR getdns_dict (3),
|
||||
.BR getdns_general (3),
|
||||
.BR getdns_general_sync (3),
|
||||
.BR getdns_hostname (3),
|
||||
.BR getdns_hostname_sync (3),
|
||||
.BR getdns_list (3),
|
||||
.BR getdns_service (3),
|
||||
.BR getdns_service_sync (3).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue