mirror of https://github.com/getdnsapi/getdns.git
added context pages
This commit is contained in:
Glen Wiley
parent
74d581d817
commit
267530909b
|
|
@ -74,42 +74,42 @@ The getdns_address(3) and getdns_address_sync functions provide public entry poi
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
.RP
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
|
||||
.RP
|
||||
the host name to resolve to an address (note that an IP address is considered invalid)
|
||||
|
||||
.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
|
||||
|
||||
.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
|
||||
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
|
||||
|
|
@ -164,6 +164,7 @@ TBD
|
|||
|
||||
.SH SEE ALSO
|
||||
.BR libgetdns (3),
|
||||
.BR getdns_context (3),
|
||||
.BR getdns_general (3),
|
||||
.BR getdns_general_sync (3),
|
||||
.BR getdns_hostname (3),
|
||||
|
|
|
|||
|
|
@ -0,0 +1,169 @@
|
|||
.\" 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_context 3 "@date@" "getdns @version@" getdns
|
||||
.SH NAME
|
||||
.B getdns_context_create,
|
||||
.B getdns_context_create_with_memory_functions,
|
||||
.B getdns_context_create_with_extended_memory_functions,
|
||||
.B getdns_context_destroy
|
||||
-- getdns context create and destroy routines
|
||||
|
||||
.SH LIBRARY
|
||||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
#include <getdns.h>
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_create
|
||||
(struct getdns_context ** context,
|
||||
.RS 3
|
||||
.br
|
||||
int set_from_os)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_create_with_memory_functions
|
||||
(struct getdns_context ** context,
|
||||
.RS 3
|
||||
.br
|
||||
int set_from_os,
|
||||
.br
|
||||
void *(*malloc) (size_t),
|
||||
.br
|
||||
void *(*realloc) (void *, size_t),
|
||||
.br
|
||||
void (*free) (void *))
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_create_with_extended_memory_functions
|
||||
(struct getdns_context **context,
|
||||
.RS 3
|
||||
.br
|
||||
int set_from_os,
|
||||
.br
|
||||
void *userarg,
|
||||
.br
|
||||
void *(*malloc) (void *userarg, size_t),
|
||||
.br
|
||||
void *(*realloc) (void *userarg, void *, size_t),
|
||||
.br
|
||||
void (*free) (void *userarg, void *))
|
||||
.RE
|
||||
|
||||
void
|
||||
.br
|
||||
.B getdns_context_destroy
|
||||
(struct getdns_context *context)
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.LP
|
||||
Many calls in the DNS API require a DNS context. A DNS context contains the information that the API needs in order to process DNS calls, such as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. The internal structure of the DNS context is opaque, and might be different on each OS. When a context is passed to any function, it must be an allocated context; the context must not be NULL.
|
||||
|
||||
.LP
|
||||
A typical application using this API doesn't need to know anything about contexts. Basically, the application creates a default context, uses it in the functions that require a context, and then deallocates it when done. Context manipulation is available for more DNS-aware programs, but is unlikely to be of interest to applications that just want the results of lookups for A, AAAA, SRV, and PTR records.
|
||||
|
||||
.LP
|
||||
It is expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile. A context should not be used by multiple threads: create a new context for use on a different thread. It is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread.
|
||||
|
||||
.LP
|
||||
When the context is used in the API for the first time and set_from_os is 1, the API starts replacing some of the values with values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the API to change the values to the OS's defaults; if set_from_os is 0, the API will not do any updates to the initial values based on changes in the OS. For example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
In calls to the getdns_create_context functions this parameter is used to return a newly allocated and initialized context (if there are no errors). In the getdns_destroy_context function this is the context whose associated memory will be released.
|
||||
|
||||
.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.
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
.RP
|
||||
In the extended use case this argument is passed unchanged to each of the memory management functions each time they are called.
|
||||
|
||||
.HP 3
|
||||
.I malloc
|
||||
.RP
|
||||
The function that will be used for creating response dicts (and the members within the response dicts). By default the system malloc is used.
|
||||
|
||||
.HP 3
|
||||
.I realloc
|
||||
.RP
|
||||
The function that will be used for creating response dicts (and the members within the response dicts). By default the system realloc is used.
|
||||
|
||||
.HP 3
|
||||
.I free
|
||||
.RP
|
||||
The function that will be used for releasing storage for response dicts (and the members within the response dicts). By default the system free is used.
|
||||
|
||||
.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 while initializing the context
|
||||
|
||||
.LP
|
||||
.B GETDNS_RETURN_BAD_CONTEXT
|
||||
if the context pointer is invalid (getdns_context_destroy)
|
||||
|
||||
.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_context_set (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).
|
||||
|
||||
|
|
@ -0,0 +1,174 @@
|
|||
.\" 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_context_set 3 "@date@" "getdns @version@" getdns
|
||||
.SH NAME
|
||||
.B getdns_context_set_context_update_callback,
|
||||
.B getdns_context_set_dns_transport,
|
||||
.B getdns_context_set_limit_outstanding_queries,
|
||||
.B getdns_context_set_namespaces,
|
||||
.B getdns_context_set_resolution_type,
|
||||
.B getdns_context_set_timeout
|
||||
-- getdns context manipulation routines
|
||||
|
||||
.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_t context,
|
||||
.RS 3
|
||||
.br
|
||||
(*callback)(struct getdns_context *context, uint16_t changed_item))
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_set_dns_transport
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
.br
|
||||
uint16_t transport)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_set_limit_outstanding_queries
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
.br
|
||||
uint16_t limit)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_set_namespaces
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
.br
|
||||
size_t namespace_count,
|
||||
.br
|
||||
uint16_t *namespaces)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_set_resolution_type
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
uint16_t restype)
|
||||
.RE
|
||||
|
||||
getdns_return_t
|
||||
.br
|
||||
.B getdns_context_set_timeout
|
||||
(getdns_context_t context,
|
||||
.RS 3
|
||||
uint16_t timeout)
|
||||
.RE
|
||||
|
||||
.SH DESCRIPTION
|
||||
|
||||
.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.
|
||||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
a previously allocated and initialized getdns_context
|
||||
|
||||
.HP 3
|
||||
.I callback
|
||||
.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 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 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.
|
||||
|
||||
.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.
|
||||
|
||||
.HP 3
|
||||
.I restype
|
||||
.RP
|
||||
can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_STUB (requires that forwarders be specified by the caller).
|
||||
|
||||
.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.
|
||||
|
||||
.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_CONTEXT_UPDATE_FAIL
|
||||
if there was a problem updating the context
|
||||
|
||||
.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_context (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).
|
||||
|
||||
|
|
@ -78,12 +78,12 @@ The getdns_general(3) and getdns_general_sync functions provide public entry poi
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
|
||||
.RP
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
|
||||
.RP
|
||||
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
|
||||
|
|
@ -91,37 +91,36 @@ to allow non-ASCII octets and special characters in labels.
|
|||
|
||||
.HP 3
|
||||
.I request_type
|
||||
|
||||
.RP
|
||||
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
|
||||
|
||||
.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
|
||||
|
||||
.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
|
||||
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
|
||||
|
|
@ -144,7 +143,7 @@ if the data type specified in one or more of the extensions does not match the s
|
|||
.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:
|
||||
The values of status included in the response parameter are:
|
||||
|
||||
.LP
|
||||
.B GETDNS_RESPSTATUS_GOOD
|
||||
|
|
@ -260,6 +259,7 @@ TBD
|
|||
.BR libgetdns (3),
|
||||
.BR getdns_address (3),
|
||||
.BR getdns_address_sync (3),
|
||||
.BR getdns_context (3),
|
||||
.BR getdns_hostname (3),
|
||||
.BR getdns_hostname_sync (3),
|
||||
.BR getdns_service (3),
|
||||
|
|
|
|||
Loading…
Reference in New Issue