ub_resolve_async (3) - Linux Manuals
Command to display ub_resolve_async
manual in Linux: $ man 3 ub_resolve_async
NAME
libunbound,
unbound.h,
ub_ctx,
ub_result,
ub_callback_t,
ub_ctx_create,
ub_ctx_delete,
ub_ctx_set_option,
ub_ctx_get_option,
ub_ctx_config,
ub_ctx_set_fwd,
ub_ctx_resolvconf,
ub_ctx_hosts,
ub_ctx_add_ta,
ub_ctx_add_ta_file,
ub_ctx_trustedkeys,
ub_ctx_debugout,
ub_ctx_debuglevel,
ub_ctx_async,
ub_poll,
ub_wait,
ub_fd,
ub_process,
ub_resolve,
ub_resolve_async,
ub_cancel,
ub_resolve_free,
ub_strerror,
ub_ctx_print_local_zones,
ub_ctx_zone_add,
ub_ctx_zone_remove,
ub_ctx_data_add,
ub_ctx_data_remove
- Unbound DNS validating resolver 1.4.20 functions.
SYNOPSIS
#include <unbound.h>
struct ub_ctx *
ub_ctx_create(void);
void
ub_ctx_delete(struct ub_ctx* ctx);
int
ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val);
int
ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val);
int
ub_ctx_config(struct ub_ctx* ctx, char* fname);
int
ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr);
int
ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname);
int
ub_ctx_hosts(struct ub_ctx* ctx, char* fname);
int
ub_ctx_add_ta(struct ub_ctx* ctx, char* ta);
int
ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname);
int
ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname);
int
ub_ctx_debugout(struct ub_ctx* ctx, FILE* out);
int
ub_ctx_debuglevel(struct ub_ctx* ctx, int d);
int
ub_ctx_async(struct ub_ctx* ctx, int dothread);
int
ub_poll(struct ub_ctx* ctx);
int
ub_wait(struct ub_ctx* ctx);
int
ub_fd(struct ub_ctx* ctx);
int
ub_process(struct ub_ctx* ctx);
int
ub_resolve(struct ub_ctx* ctx, char* name,
int rrtype, int rrclass, struct ub_result** result);
int
ub_resolve_async(struct ub_ctx* ctx, char* name,
int rrtype, int rrclass, void* mydata,
ub_callback_t callback, int* async_id);
int
ub_cancel(struct ub_ctx* ctx, int async_id);
void
ub_resolve_free(struct ub_result* result);
const char *
ub_strerror(int err);
int
ub_ctx_print_local_zones(struct ub_ctx* ctx);
int
ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type);
int
ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name);
int
ub_ctx_data_add(struct ub_ctx* ctx, char* data);
int
ub_ctx_data_remove(struct ub_ctx* ctx, char* data);
DESCRIPTION
Unbound
is an implementation of a DNS resolver, that does caching and
DNSSEC validation. This is the library API, for using the -lunbound library.
The server daemon is described in unbound(8).
The library can be used to convert hostnames to ip addresses, and back,
and obtain other information from the DNS. The library performs public-key
validation of results with DNSSEC.
The library uses a variable of type struct ub_ctx to keep context
between calls. The user must maintain it, creating it with
ub_ctx_create
and deleting it with
ub_ctx_delete.
It can be created and deleted at any time. Creating it anew removes any
previous configuration (such as trusted keys) and clears any cached results.
The functions are thread-safe, and a context an be used in a threaded (as
well as in a non-threaded) environment. Also resolution (and validation)
can be performed blocking and non-blocking (also called asynchronous).
The async method returns from the call immediately, so that processing
can go on, while the results become available later.
The functions are discussed in turn below.
FUNCTIONS
- ub_ctx_create
-
Create a new context, initialised with defaults.
The information from /etc/resolv.conf and /etc/hosts is not utilised
by default. Use
ub_ctx_resolvconf
and
ub_ctx_hosts
to read them.
- ub_ctx_delete
-
Delete validation context and free associated resources.
Outstanding async queries are killed and callbacks are not called for them.
- ub_ctx_set_option
-
A power-user interface that lets you specify one of the options from the
config file format, see unbound.conf(5). Not all options are
relevant. For some specific options, such as adding trust anchors, special
routines exist. Pass the option name with the trailing ':'.
- ub_ctx_get_option
-
A power-user interface that gets an option value. Some options cannot be
gotten, and others return a newline separated list. Pass the option name
without trailing ':'. The returned value must be free(2)d by the caller.
- ub_ctx_config
-
A power-user interface that lets you specify an unbound config file, see
unbound.conf(5), which is read for configuration. Not all options are
relevant. For some specific options, such as adding trust anchors, special
routines exist.
- ub_ctx_set_fwd
-
Set machine to forward DNS queries to, the caching resolver to use.
IP4 or IP6 address. Forwards all DNS requests to that machine, which
is expected to run a recursive resolver. If the proxy is not
DNSSEC capable, validation may fail. Can be called several times, in
that case the addresses are used as backup servers.
At this time it is only possible to set configuration before the
first resolve is done.
- ub_ctx_resolvconf
-
By default the root servers are queried and full resolver mode is used, but
you can use this call to read the list of nameservers to use from the
filename given.
Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
If they do not support DNSSEC, validation may fail.
Only nameservers are picked up, the searchdomain, ndots and other
settings from resolv.conf(5) are ignored.
If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
the system-wide configured nameserver is picked instead).
At this time it is only possible to set configuration before the
first resolve is done.
- ub_ctx_hosts
-
Read list of hosts from the filename given.
Usually "/etc/hosts". When queried for, these addresses are not marked
DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
(if on Windows, etc/hosts from WINDIR is picked instead).
At this time it is only possible to set configuration before the
first resolve is done.
- ub_ctx_add_ta
-
Add a trust anchor to the given context.
At this time it is only possible to add trusted keys before the
first resolve is done.
The format is a string, similar to the zone-file format,
[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
- ub_ctx_add_ta_file
-
Add trust anchors to the given context.
Pass name of a file with DS and DNSKEY records in zone file format.
At this time it is only possible to add trusted keys before the
first resolve is done.
- ub_ctx_trustedkeys
-
Add trust anchors to the given context.
Pass the name of a bind-style config file with trusted-keys{}.
At this time it is only possible to add trusted keys before the
first resolve is done.
- ub_ctx_debugout
-
Set debug and error log output to the given stream. Pass NULL to disable
output. Default is stderr. File-names or using syslog can be enabled
using config options, this routine is for using your own stream.
- ub_ctx_debuglevel
-
Set debug verbosity for the context. Output is directed to stderr.
Higher debug level gives more output.
- ub_ctx_async
-
Set a context behaviour for asynchronous action.
if set to true, enables threading and a call to
ub_resolve_async
creates a thread to handle work in the background.
If false, a process is forked to handle work in the background.
Changes to this setting after
ub_resolve_async
calls have been made have no effect (delete and re-create the context
to change).
- ub_poll
-
Poll a context to see if it has any new results.
Do not poll in a loop, instead extract the fd below to poll for readiness,
and then check, or wait using the wait routine.
Returns 0 if nothing to read, or nonzero if a result is available.
If nonzero, call
ub_process
to do callbacks.
- ub_wait
-
Wait for a context to finish with results. Calls
ub_process
after the wait for you. After the wait, there are no more outstanding
asynchronous queries.
- ub_fd
-
Get file descriptor. Wait for it to become readable, at this point
answers are returned from the asynchronous validating resolver.
Then call the ub_process to continue processing.
- ub_process
-
Call this routine to continue processing results from the validating
resolver (when the fd becomes readable).
Will perform necessary callbacks.
- ub_resolve
-
Perform resolution and validation of the target name.
The name is a domain name in a zero terminated text string.
The rrtype and rrclass are DNS type and class codes.
The result structure is newly allocated with the resulting data.
- ub_resolve_async
-
Perform asynchronous resolution and validation of the target name.
Arguments mean the same as for ub_resolve except no
data is returned immediately, instead a callback is called later.
The callback receives a copy of the mydata pointer, that you can use to pass
information to the callback. The callback type is a function pointer to
a function declared as
-
void my_callback_function(void* my_arg, int err,
struct ub_result* result);
-
The async_id is returned so you can (at your option) decide to track it
and cancel the request if needed. If you pass a NULL pointer the async_id
is not returned.
- ub_cancel
-
Cancel an async query in progress. This may return an error if the query
does not exist, or the query is already being delivered, in that case you
may still get a callback for the query.
- ub_resolve_free
-
Free struct ub_result contents after use.
- ub_strerror
-
Convert error value from one of the unbound library functions
to a human readable string.
- ub_ctx_print_local_zones
-
Debug printout the local authority information to debug output.
- ub_ctx_zone_add
-
Add new zone to local authority info, like local-zone unbound.conf(5)
statement.
- ub_ctx_zone_remove
-
Delete zone from local authority info.
- ub_ctx_data_add
-
Add resource record data to local authority info, like local-data
unbound.conf(5) statement.
- ub_ctx_data_remove
-
Delete local authority data from the name given.
RESULT DATA STRUCTURE
The result of the DNS resolution and validation is returned as
struct ub_result. The result structure contains the following entries.
struct ub_result {
char* qname; /* text string, original question */
int qtype; /* type code asked for */
int qclass; /* class code asked for */
char** data; /* array of rdata items, NULL terminated*/
int* len; /* array with lengths of rdata items */
char* canonname; /* canonical name of result */
int rcode; /* additional error code in case of no data */
void* answer_packet; /* full network format answer packet */
int answer_len; /* length of packet in octets */
int havedata; /* true if there is data */
int nxdomain; /* true if nodata because name does not exist */
int secure; /* true if result is secure */
int bogus; /* true if a security failure happened */
char* why_bogus; /* string with error if bogus */
int ttl; /* number of seconds the result is valid */
};
If both secure and bogus are false, security was not enabled for the
domain of the query.
RETURN VALUES
Many routines return an error code. The value 0 (zero) denotes no error
happened. Other values can be passed to
ub_strerror
to obtain a readable error string.
ub_strerror
returns a zero terminated string.
ub_ctx_create
returns NULL on an error (a malloc failure).
ub_poll
returns true if some information may be available, false otherwise.
ub_fd
returns a file descriptor or -1 on error.
AUTHORS
Unbound
developers are mentioned in the CREDITS file in the distribution.
Pages related to ub_resolve_async