mirror of https://github.com/getdnsapi/getdns.git
Cannot mix 'man' and 'mdoc' macro's in manpages
+ small updates to text - change "File Descriptor Polling" to "Build-in Event loop" and removal of "Custom Event Loop Integrations" section from libgetdns.
This commit is contained in:
Willem Toorop
parent
7d98275eca
commit
46557a93dc
|
|
@ -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_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
|
||||
MANPAGES3 = libgetdns.3 getdns_address.3 getdns_cancel_callback.3 getdns_context.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
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ install: $(MANPAGES3)
|
|||
for x in $(MANPAGES3); do echo $(INSTALL) -m 644 $$x $(DESTDIR)$(mandir)/man3; $(INSTALL) -m 644 $$x $(DESTDIR)$(mandir)/man3; for altpg in $$($(srcdir)/manpgaltnames $$x); do cp $$x $$altpg; echo $(INSTALL) -m 644 $$altpg $(DESTDIR)$(mandir)/man3; $(INSTALL) -m 644 $$altpg $(DESTDIR)$(mandir)/man3; done; done
|
||||
|
||||
check: $(MANPAGES3)
|
||||
for x in $(MANPAGES3); do echo -n "$$x: "; LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings -E UTF-8 -l -Tutf8 -Z $$x >/dev/null ; done
|
||||
for x in $(MANPAGES3); do LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings -E UTF-8 -l -Tutf8 -Z $$x 2>&1 >/dev/null | awk "-vpage=$$x" '{printf("%s: ", page);print}'; done
|
||||
|
||||
uninstall:
|
||||
for x in $(MANPAGES3); do echo rm -f $(DESTDIR)$(mandir)/man3/$$x; rm -f $(DESTDIR)$(mandir)/man3/$$x; for altpg in $$($(srcdir)/manpgaltnames $$x); do echo rm -f $(DESTDIR)$(mandir)/man3/$$altpg; rm -f $(DESTDIR)$(mandir)/man3/$$altpg; done; done
|
||||
|
|
|
|||
|
|
@ -72,32 +72,26 @@ The getdns_address(3) and getdns_address_sync functions provide public entry poi
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
A pointer to the previously created DNS context that is to be used with this DNS request. 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
|
||||
non-NULL pointer to a callback function defined by the application, typically
|
||||
used to process the response. Only the asynchronous signature accepts a
|
||||
callback function, the synchronous signature does not include a callback. See
|
||||
|
|
@ -105,7 +99,6 @@ libgetdns (3) for a more detailed discussion of callback functions.
|
|||
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -57,12 +57,10 @@ return immediately, even before the callback finishes its work and returns.
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
see getdns_context (3)
|
||||
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -28,6 +28,7 @@
|
|||
|
||||
.TH getdns_context 3 "@date@" "getdns @version@" getdns
|
||||
.SH NAME
|
||||
.B getdns_context,
|
||||
.B getdns_context_create,
|
||||
.B getdns_context_create_with_memory_functions,
|
||||
.B getdns_context_create_with_extended_memory_functions,
|
||||
|
|
@ -133,32 +134,26 @@ callbacks are made.
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
Used to return the pointer to an opaque structure. The caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function. The result is 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 constructed.
|
||||
|
||||
.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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
getdns_context.3.in
|
||||
|
|
@ -219,17 +219,14 @@ specifies the number of milliseconds the API will wait for a response.
|
|||
|
||||
.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 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
|
||||
|
|
@ -239,53 +236,53 @@ 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 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 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
|
||||
.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 seconds_skew
|
||||
.RP
|
||||
the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields.
|
||||
|
||||
.HP 3
|
||||
.I suffixes
|
||||
.RP
|
||||
A list of bindatas that are strings that are to be appended based on getdns_context_set_append_name. 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 timeout
|
||||
.RP
|
||||
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 3
|
||||
.I trust_anchors
|
||||
.RP
|
||||
list of bindatas that are the DNSSEC trust anchors expressed as RDATA from the DNSKEY resource records, the default are supplied by the IANA root.
|
||||
|
||||
.HP 3
|
||||
.I when_to_append
|
||||
.RP
|
||||
The value is GETDNS_APPEND_NAME_ALWAYS, GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE, GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or GETDNS_APPEND_NAME_NEVER.
|
||||
The value is
|
||||
.RS
|
||||
.IP \(bu 3
|
||||
GETDNS_APPEND_NAME_ALWAYS,
|
||||
.IP \(bu 3
|
||||
GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
|
||||
.IP \(bu 3
|
||||
GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or
|
||||
.IP \(bu 3
|
||||
GETDNS_APPEND_NAME_NEVER.
|
||||
.RE
|
||||
|
||||
.HP
|
||||
.SH "RETURN VALUES"
|
||||
|
|
|
|||
|
|
@ -49,17 +49,15 @@ void (*cbfun)(getdns_context *context, getdns_context_code_t changed_item)
|
|||
|
||||
.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
|
||||
.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.
|
||||
|
||||
|
|
|
|||
|
|
@ -75,14 +75,12 @@ 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.
|
||||
|
|
|
|||
|
|
@ -50,7 +50,6 @@ is IPv4 or IPv6.
|
|||
|
||||
.HP 3
|
||||
.I ipv4_or_ipv6_addr
|
||||
.RP
|
||||
bindata of the address to print
|
||||
|
||||
.HP
|
||||
|
|
|
|||
|
|
@ -48,7 +48,6 @@ This function is used to free memory allocated within one of the synchronous fun
|
|||
|
||||
.HP 3
|
||||
.I response
|
||||
.RP
|
||||
A previously allocated response object.
|
||||
|
||||
.HP
|
||||
|
|
|
|||
|
|
@ -80,12 +80,10 @@ getdns_address(3) which would replace getaddrinfo(3).
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
A pointer to the previsouly created DNS context that is to be used with this DNS request. 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
|
||||
|
|
@ -93,27 +91,22 @@ 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
|
||||
.RP
|
||||
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
|
||||
non-NULL pointer to a callback function defined by the application, typically
|
||||
used to process the response. Only the asynchronous signature accepts a
|
||||
callback function, the synchronous signature does not include a callback. See
|
||||
|
|
@ -121,7 +114,6 @@ libgetdns (3) for a more detailed discussion of callback functions.
|
|||
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -80,22 +80,18 @@ a getdns_dict structure containing two names: address_type (whose value is binda
|
|||
|
||||
.HP 3
|
||||
.I extensions
|
||||
.RP
|
||||
extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
.RP
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
.RP
|
||||
populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails
|
||||
|
||||
.HP 3
|
||||
.I callbackfn
|
||||
.RP
|
||||
non-NULL pointer to a callback function defined by the application, typically
|
||||
used to process the response. Only the asynchronous signature accepts a
|
||||
callback function, the synchronous signature does not include a callback. See
|
||||
|
|
@ -103,7 +99,6 @@ libgetdns (3) for a more detailed discussion of callback functions.
|
|||
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -49,7 +49,6 @@ elements in the dict.
|
|||
|
||||
.HP 3
|
||||
.I this_dict
|
||||
.RP
|
||||
the dictionary to render as a string
|
||||
|
||||
.HP
|
||||
|
|
|
|||
|
|
@ -54,7 +54,6 @@ helper function.
|
|||
|
||||
.HP 3
|
||||
.I utc_date_of_anchor
|
||||
.RP
|
||||
time the trust anchors were obtained in epoch seconds (on success)
|
||||
|
||||
.HP
|
||||
|
|
|
|||
|
|
@ -72,32 +72,26 @@ The getdns_service (3) and getdns_service_sync functions provide public entry po
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
A pointer to the previously created DNS context that is to be used with this DNS request. see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I name
|
||||
.RP
|
||||
the service name to resolve
|
||||
|
||||
.HP 3
|
||||
.I extensions
|
||||
.RP
|
||||
extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions
|
||||
|
||||
.HP 3
|
||||
.I userarg
|
||||
.RP
|
||||
returned to the callback function untouched, can be NULL
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
.RP
|
||||
populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails
|
||||
|
||||
.HP 3
|
||||
.I callbackfn
|
||||
.RP
|
||||
non-NULL pointer to a callback function defined by the application, typically
|
||||
used to process the response. Only the asynchronous signature accepts a
|
||||
callback function, the synchronous signature does not include a callback. See
|
||||
|
|
@ -105,7 +99,6 @@ libgetdns (3) for a more detailed discussion of callback functions.
|
|||
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -60,17 +60,14 @@ helper function.
|
|||
|
||||
.HP 3
|
||||
.I record_to_validate
|
||||
.RP
|
||||
the resource record being validated
|
||||
|
||||
.HP 3
|
||||
.I bundle_of_support_records
|
||||
.RP
|
||||
records used to construct the validation chain
|
||||
|
||||
.HP 3
|
||||
.I trust_anchor_records
|
||||
.RP
|
||||
trust anchor records to use for the validation
|
||||
|
||||
.HP
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ libgetdns
|
|||
DNS Resolver library (libgetdns, -lgetdns)
|
||||
|
||||
.SH SYNOPSIS
|
||||
.Lb libgetdns
|
||||
.B libgetdns
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -59,12 +59,12 @@ A context structure maintains DNS query and response data and is used to maintai
|
|||
.LP
|
||||
The project page for this implementation is at
|
||||
.IP
|
||||
http://www.getdnsapi.net
|
||||
http://getdnsapi.net
|
||||
|
||||
.LP
|
||||
The specification is maintained at
|
||||
.IP
|
||||
http://www.vpnc.org/getdns-api
|
||||
http://getdnsapi.net/spec
|
||||
|
||||
.LP
|
||||
The git repository for this implementation is at
|
||||
|
|
@ -113,16 +113,16 @@ Custom Event Loop Integrations
|
|||
.LP
|
||||
All functions and types discussed in this page are declared in getdns_extra.h
|
||||
|
||||
.SS "File Descriptor Polling"
|
||||
.SS "Build-in Event loop"
|
||||
|
||||
A common approach used in asynchronous applications is to poll a file
|
||||
descriptor via system calls like select and poll and then yielding CPU when
|
||||
ready. The API provides the following functions to support this approach:
|
||||
The library has an built in event loop that can be used if none of the extensions for external event loops are used. The library will execute requests and dispatch callbacks with a call to
|
||||
.I getdns_context_run().
|
||||
If an event loop extension is used, this will run the extension's eventloop.
|
||||
|
||||
.HP 3
|
||||
int getdns_context_fd(getdns_context* context)
|
||||
void getdns_context_run(getdns_context *context)
|
||||
|
||||
Get the file descriptor to poll for a given context. Callers should never read from this result. It is meant strictly for polling.Returns -1 if the context is NULL.
|
||||
Run the context's event loop until nothing more to do.
|
||||
|
||||
.HP 3
|
||||
uint32_t getdns_context_get_num_pending_requests(getdns_context* context, struct timeval* next_timeout)
|
||||
|
|
@ -134,26 +134,6 @@ getdns_return_t getdns_context_process_async(getdns_context* context)
|
|||
|
||||
Inform the context to process its outstanding requests. Users should call this when either a timeout has occurred or the file descriptor signals that it is ready. User callbacks are fired during this call.
|
||||
|
||||
.SS "Example Event Loop"
|
||||
|
||||
The following is an example event loop leveraging select:
|
||||
|
||||
.Bd -literal -compact
|
||||
struct timeval tv;
|
||||
/* Keep looping while there are outstanding requests */
|
||||
while (getdns_context_get_num_pending_requests(context, &tv) > 0)
|
||||
{
|
||||
/* setup the read FD_SET to pass to select */
|
||||
int fd = getdns_context_fd(context);
|
||||
fd_set read_fds;
|
||||
FD_ZERO(&read_fds);
|
||||
FD_SET(fd, &read_fds);
|
||||
/* Wait on the FD or for a timeout */
|
||||
select(fd + 1, &read_fds, NULL, NULL, &tv);
|
||||
getdns_context_process_async(context);
|
||||
}
|
||||
.Ed
|
||||
|
||||
.SS "Included Event Loop Integrations"
|
||||
|
||||
.LP
|
||||
|
|
@ -198,77 +178,6 @@ Extension library: libgetdns_ext_ev.[shared_lib_ext]
|
|||
Extension header: getdns_ext_libev.h
|
||||
.RE
|
||||
|
||||
.SS "Custom Event Loop Integrations"
|
||||
|
||||
.LP
|
||||
The event loop integrations documented above all leverage the same event loop extension API provided by this library. The mechanism is exposed to developers who wish to integrate their own event loop. And includes the following functions and structures:
|
||||
|
||||
.LP
|
||||
The application provides a callback to indicate that a timeout has occurred.
|
||||
|
||||
.IP
|
||||
typedef void (*getdns_timeout_callback) (void* userarg);
|
||||
|
||||
.LP
|
||||
Timeout data provided when scheduling a timeout is captured in this structure:
|
||||
|
||||
.Bd -literal -compact
|
||||
typedef struct getdns_timeout_data {
|
||||
/* a timeout id */
|
||||
getdns_transaction_t transaction_id;
|
||||
/* absolute time of the timeout */
|
||||
struct timeval timeout_time;
|
||||
/* the timeout callback to fire */
|
||||
getdns_timeout_callback callback;
|
||||
/* user arg to callback */
|
||||
void* userarg;
|
||||
/* pointer to the underlying extension pointer that the extension will create and free */
|
||||
void* extension_timer;
|
||||
struct getdns_context* context;
|
||||
} getdns_timeout_data_t;
|
||||
.Ed
|
||||
|
||||
.LP
|
||||
The application calls the extension to schedule a timer. Any timer data that needs to be tracked should be stored in eventloop_timer.
|
||||
|
||||
.IP
|
||||
typedef getdns_return_t (*getdns_eventloop_schedule_timeout_t)(struct getdns_context* context,
|
||||
void* eventloop_data, uint16_t timeout,
|
||||
getdns_timeout_data_t* timeout_data,
|
||||
void** eventloop_timer);
|
||||
|
||||
.LP
|
||||
The application calls the extension to free a timer. The timer passed in is the same as that returned in the schedule timeout. This is the only place where it is safe to free timer data. Extensions can expect this will be called for every schedule_timeout call.
|
||||
|
||||
.IP
|
||||
typedef getdns_return_t (*getdns_eventloop_clear_timeout_t)(struct getdns_context* context,
|
||||
void* eventloop_data, void* eventloop_timer);
|
||||
|
||||
.LP
|
||||
The application informs the extension that the number of outbound requests has changed. This is called when an asynchronous request is submitted or canceled by the user.
|
||||
|
||||
.IP
|
||||
typedef getdns_return_t (*getdns_eventloop_request_count_changed_t)(struct getdns_context* context, uint32_t request_count, void* eventloop_data);
|
||||
|
||||
.LP
|
||||
The application tell the extension to free up any data associated with the extension functions. This is called when a context is destroyed, or the extension is being detached.
|
||||
|
||||
.IP
|
||||
typedef getdns_return_t (*getdns_eventloop_cleanup_t)(struct getdns_context* context, void* eventloop_data);
|
||||
|
||||
.LP
|
||||
The extension structure used by the getdns_context.
|
||||
|
||||
.IP
|
||||
typedef struct getdns_eventloop_extension {
|
||||
getdns_eventloop_cleanup_t cleanup_data;
|
||||
getdns_eventloop_schedule_timeout_t schedule_timeout;
|
||||
getdns_eventloop_clear_timeout_t clear_timeout;
|
||||
getdns_eventloop_request_count_changed_t request_count_changed;
|
||||
} getdns_eventloop_extension;
|
||||
|
||||
.Ed
|
||||
|
||||
.SS "getdns_context event loop extension functions"
|
||||
|
||||
.LP
|
||||
|
|
@ -325,7 +234,7 @@ and
|
|||
.I replies_full lists
|
||||
|
||||
.HP 3
|
||||
dnssec_return_supporting_responses (int)
|
||||
dnssec_return_validation_chain (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
|
||||
|
|
@ -390,12 +299,12 @@ dnssec_status (an int) added to the other names in the record's dict ("header",
|
|||
GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, and GETDNS_DNSSEC_INSECURE.
|
||||
Thus, a reply might look like:
|
||||
|
||||
.Bd -literal -compact
|
||||
.EX
|
||||
{ # This is the first reply
|
||||
"dnssec_status": GETDNS_DNSSEC_INDETERMINATE,
|
||||
"header": { "id": 23456, "qr": 1, "opcode": 0, ... },
|
||||
. . .
|
||||
.Ed
|
||||
.EE
|
||||
|
||||
.LP
|
||||
If instead of returning the status, you want to only see secure results, use
|
||||
|
|
@ -419,7 +328,7 @@ includes all resource record dicts for all the resource records (DS, DNSKEY and
|
|||
their RRSIGs) that are needed to perform the validation from the root up. Thus,
|
||||
a reply might look like:
|
||||
|
||||
.Bd -literal -compact
|
||||
.EX
|
||||
{ # This is the response object
|
||||
"validation_chain":
|
||||
[ { "name": <bindata for .>,
|
||||
|
|
@ -491,7 +400,7 @@ a reply might look like:
|
|||
"replies_tree":
|
||||
[
|
||||
. . .
|
||||
.Ed
|
||||
.EE
|
||||
|
||||
.LP
|
||||
If a request is using a context in which stub resolution is set, and that
|
||||
|
|
@ -509,27 +418,22 @@ the parameters; these are described in more detail in RFC 2671. They are:
|
|||
|
||||
.HP 3
|
||||
.I maximum_udp_payload_size
|
||||
.RP
|
||||
(an int) between 512 and 65535; if not specified, this defaults to those from the DNS context
|
||||
|
||||
.HP 3
|
||||
.I extended_rcode
|
||||
.RP
|
||||
(an int) between 0 and 255; if not specified, this defaults to those from the DNS context
|
||||
|
||||
.HP 3
|
||||
.I version
|
||||
.RP
|
||||
(an int) between 0 and 255; if not specified, this defaults to 0
|
||||
|
||||
.HP 3
|
||||
.I do_bit
|
||||
.RP
|
||||
(an int) between 0 and 1; if not specified, this defaults to those from the DNS context
|
||||
|
||||
.HP 3
|
||||
.I options
|
||||
.RP
|
||||
(a list) contains dicts for each option to be specified. Each list time
|
||||
contains two names: option_code (an int) and option_data (a bindata). The API
|
||||
marshalls the entire set of options into a properly-formatted RDATA for the
|
||||
|
|
@ -705,12 +609,10 @@ getdns_transaction_t transaction_id)
|
|||
|
||||
.HP 3
|
||||
.I context
|
||||
.RP
|
||||
see getdns_context (3)
|
||||
|
||||
.HP 3
|
||||
.I callback_type
|
||||
.RP
|
||||
Supplies the reason for the callback.
|
||||
.RS 3
|
||||
.LP
|
||||
|
|
@ -729,7 +631,6 @@ The requested action had an error; response is NULL
|
|||
|
||||
.HP 3
|
||||
.I response
|
||||
.RP
|
||||
A response object with the response data. This is described in the section
|
||||
titled "RESPONSE DATA" elsewhere in this manual page. The response object is
|
||||
part of the API's memory space, and will be freed by the API with the callback
|
||||
|
|
@ -737,12 +638,10 @@ returns.
|
|||
|
||||
.HP 3
|
||||
.I userarg
|
||||
.RP
|
||||
Identical to the userarg passed to the calling function.
|
||||
|
||||
.HP 3
|
||||
.I transaction_id
|
||||
.RP
|
||||
The transaction identified assigned by the calling function, used to associate a DNS response to a specific DNS request.
|
||||
|
||||
.LP
|
||||
|
|
|
|||
Loading…
Reference in New Issue