Cancel an async query in progress.
Its callback will not be called.
Add a trust anchor to the given context.
The trust anchor is a string, on one line, that holds a valid DNSKEY or
DS RR.
@param ctx: context.
At this time it is only possible to add trusted keys before the
first resolve is done.
@param ta: string, with zone-format RR on one line.
[domainname] [TTL optional] [type] [class optional] [rdata contents]
@return 0 if OK, else error.
Add trust anchor to the given context that is tracked with RFC5011
automated trust anchor maintenance. The file is written to when the
trust anchor is changed.
Pass the name of a file that was output from eg. unbound-anchor,
or you can start it by providing a trusted DNSKEY or DS record on one
line in the file.
@param ctx: context.
At this time it is only possible to add trusted keys before the
first resolve is done.
@param fname: filename of file with trust anchor.
@return 0 if OK, else error.
Add trust anchors to the given context.
Pass name of a file with DS and DNSKEY records (like from dig or drill).
@param ctx: context.
At this time it is only possible to add trusted keys before the
first resolve is done.
@param fname: filename of file with keyfile with trust anchors.
@return 0 if OK, else error.
Set a context behaviour for asynchronous action.
@param ctx: context.
@param dothread: if true, enables threading and a call to 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 async() calls have been made have
no effect (delete and re-create the context to change).
@return 0 if OK, else error.
setup configuration for the given context.
@param ctx: context.
@param fname: unbound config file (not all settings applicable).
This is a power-users interface that lets you specify all sorts
of options.
For some specific options, such as adding trust anchors, special
routines exist.
@return: 0 if OK, else error.
Create a resolving and validation context.
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.
@return a new context. default initialisation.
returns NULL on error.
Add localdata to the library local authority info.
Similar to local-data config statement.
@param ctx: context. Is finalized by the routine.
@param data: the resource record in text format, for example
“www.example.com IN A 127.0.0.1”
@return 0 if OK, else error.
Remove localdata from the library local authority info.
@param ctx: context. Is finalized by the routine.
@param data: the name to delete all data from, like “www.example.com”.
@return 0 if OK, else error.
Set debug verbosity for the context
Output is directed to stderr.
@param ctx: context.
@param d: debug level, 0 is off, 1 is very minimal, 2 is detailed,
and 3 is lots.
@return 0 if OK, else error.
Set debug output (and error output) to the specified stream.
Pass NULL to disable. Default is stderr.
@param ctx: context.
@param out: FILE* out file stream to log to.
Type void* to avoid stdio dependency of this header file.
@return 0 if OK, else error.
Destroy a validation context and free all its resources.
Outstanding async queries are killed and callbacks are not called for them.
@param ctx: context to delete.
Get an option from the context.
@param ctx: context.
@param opt: option name from the unbound.conf config file format.
(not all settings applicable). The name excludes the trailing ‘:’
for example ub_ctx_get_option(ctx, “logfile”, &result);
This is a power-users interface that lets you specify all sorts
of options.
@param str: the string is malloced and returned here. NULL on error.
The caller must free() the string. In cases with multiple
entries (auto-trust-anchor-file), a newline delimited list is
returned in the string.
@return 0 if OK else an error code (malloc failure, syntax error).
Read list of hosts from the filename given.
Usually “/etc/hosts”.
These addresses are not flagged as DNSSEC secure when queried for.
Debug routine. Print the local zone information to debug output.
@param ctx: context. Is finalized by the routine.
@return 0 if OK, else error.
Read 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.
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.
Set an option for the context.
@param ctx: context.
@param opt: option name from the unbound.conf config file format.
(not all settings applicable). The name includes the trailing ‘:’
for example ub_ctx_set_option(ctx, “logfile:”, “mylog.txt”);
This is a power-users interface that lets you specify all sorts
of options.
For some specific options, such as adding trust anchors, special
routines exist.
@param val: value of the option.
@return: 0 if OK, else error.
Add a stub zone, with given address to send to. This is for custom
root hints or pointing to a local authoritative dns server.
For dns resolvers and the ‘DHCP DNS’ ip address, use ub_ctx_set_fwd.
This is similar to a stub-zone entry in unbound.conf.
Use DNS over TLS to send queries to machines set with ub_ctx_set_fwd().
Add trust anchors to the given context.
Pass the name of a bind-style config file with trusted-keys{}.
@param ctx: context.
At this time it is only possible to add trusted keys before the
first resolve is done.
@param fname: filename of file with bind-style config entries with trust
anchors.
@return 0 if OK, else error.
Add a new zone with the zonetype to the local authority info of the
library.
@param ctx: context. Is finalized by the routine.
@param zone_name: name of the zone in text, “example.com”
If it already exists, the type is updated.
@param zone_type: type of the zone (like for unbound.conf) in text.
@return 0 if OK, else error.
Remove zone from local authority info of the library.
@param ctx: context. Is finalized by the routine.
@param zone_name: name of the zone in text, “example.com”
If it does not exist, nothing happens.
@return 0 if OK, else error.
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.
This routine works immediately after context creation, the fd
does not change.
@param ctx: context.
@return: -1 on error, or file descriptor to use select(2) with.
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.
@param ctx: context.
@return: 0 if nothing to read, or nonzero if a result is available.
If nonzero, call ctx_process() to do callbacks.
Call this routine to continue processing results from the validating
resolver (when the fd becomes readable).
Will perform necessary callbacks.
@param ctx: context
@return: 0 if OK, else error.
Perform resolution and validation of the target name.
@param ctx: context.
The context is finalized, and can no longer accept config changes.
@param name: domain name in text format (a zero terminated text string).
@param rrtype: type of RR in host order, 1 is A (address).
@param rrclass: class of RR in host order, 1 is IN (for internet).
@param result: the result data is returned in a newly allocated result
structure. May be NULL on return, return value is set to an error
in that case (out of memory).
@return 0 if OK, else error.
Perform resolution and validation of the target name.
Asynchronous, after a while, the callback will be called with your
data and the result.
@param ctx: context.
If no thread or process has been created yet to perform the
work in the background, it is created now.
The context is finalized, and can no longer accept config changes.
@param name: domain name in text format (a string).
@param rrtype: type of RR in host order, 1 is A.
@param rrclass: class of RR in host order, 1 is IN (for internet).
@param mydata: this data is your own data (you can pass NULL),
and is passed on to the callback function.
@param callback: this is called on completion of the resolution.
It is called as:
void callback(void* mydata, int err, struct ub_result* result)
with mydata: the same as passed here, you may pass NULL,
with err: is 0 when a result has been found.
with result: a newly allocated result structure.
The result may be NULL, in that case err is set.
Free storage associated with a result structure.
@param result: to free
Convert error value to a human readable string.
@param err: error code from one of the libunbound functions.
The error codes are from the type enum ub_ctx_err.
@return pointer to constant text string, zero terminated.
Get a version string from the libunbound implementation.
@return a static constant string with the version number.
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.
@param ctx: context.
@return: 0 if OK, else error.