diff options
Diffstat (limited to 'contrib/unbound/doc/libunbound.3.in')
| -rw-r--r-- | contrib/unbound/doc/libunbound.3.in | 675 |
1 files changed, 331 insertions, 344 deletions
diff --git a/contrib/unbound/doc/libunbound.3.in b/contrib/unbound/doc/libunbound.3.in index 8ef33b0998a2..e3723fbbdbad 100644 --- a/contrib/unbound/doc/libunbound.3.in +++ b/contrib/unbound/doc/libunbound.3.in @@ -1,335 +1,306 @@ -.TH "libunbound" "3" "Jul 16, 2025" "NLnet Labs" "unbound 1.23.1" -.\" -.\" libunbound.3 -- unbound library functions manual -.\" -.\" Copyright (c) 2007, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -.B libunbound, -.B unbound.h, -.B ub_ctx, -.B ub_result, -.B ub_callback_type, -.B ub_ctx_create, -.B ub_ctx_delete, -.B ub_ctx_set_option, -.B ub_ctx_get_option, -.B ub_ctx_config, -.B ub_ctx_set_fwd, -.B ub_ctx_set_stub, -.B ub_ctx_set_tls, -.B ub_ctx_resolvconf, -.B ub_ctx_hosts, -.B ub_ctx_add_ta, -.B ub_ctx_add_ta_autr, -.B ub_ctx_add_ta_file, -.B ub_ctx_trustedkeys, -.B ub_ctx_debugout, -.B ub_ctx_debuglevel, -.B ub_ctx_async, -.B ub_poll, -.B ub_wait, -.B ub_fd, -.B ub_process, -.B ub_resolve, -.B ub_resolve_async, -.B ub_cancel, -.B ub_resolve_free, -.B ub_strerror, -.B ub_ctx_print_local_zones, -.B ub_ctx_zone_add, -.B ub_ctx_zone_remove, -.B ub_ctx_data_add, -.B ub_ctx_data_remove -\- Unbound DNS validating resolver 1.23.1 functions. -.SH "SYNOPSIS" -.B #include <unbound.h> -.LP -\fIstruct ub_ctx *\fR -\fBub_ctx_create\fR(\fIvoid\fR); -.LP -\fIvoid\fR -\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val); -.LP -\fIint\fR -\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val); -.LP -\fIint\fR -\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr); -.LP -\fIint\fR -\fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone, -\fIchar*\fR addr, -.br - \fIint\fR isprime); -.LP -\fIint\fR -\fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls); -.LP -\fIint\fR -\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta); -.LP -\fIint\fR -\fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out); -.LP -\fIint\fR -\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d); -.LP -\fIint\fR -\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread); -.LP -\fIint\fR -\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_process\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, -.br - \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result); -.LP -\fIint\fR -\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, -.br - \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata, -.br - \fIub_callback_type\fR callback, \fIint*\fR async_id); -.LP -\fIint\fR -\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id); -.LP -\fIvoid\fR -\fBub_resolve_free\fR(\fIstruct ub_result*\fR result); -.LP -\fIconst char *\fR -\fBub_strerror\fR(\fIint\fR err); -.LP -\fIint\fR -\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); -.LP -\fIint\fR -\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); -.LP -\fIint\fR -\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); -.LP -\fIint\fR -\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); -.SH "DESCRIPTION" -.B 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 \fIunbound\fR(8). -The library works independent from a running unbound server, and -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. -.P -The library uses a variable of type \fIstruct ub_ctx\fR to keep context -between calls. The user must maintain it, creating it with -.B ub_ctx_create -and deleting it with -.B ub_ctx_delete\fR. -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. -.P -The functions are thread\-safe, and a context can 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. -.P +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "LIBUNBOUND" "3" "Sep 18, 2025" "1.24.0" "Unbound" +.SH NAME +libunbound \- Unbound DNS validating resolver 1.24.0 functions. +.SH SYNOPSIS +.sp +\fB#include <unbound.h>\fP +.sp +struct ub_ctx * \fBub_ctx_create\fP(void); +.sp +void \fBub_ctx_delete\fP(struct ub_ctx* ctx); +.sp +int \fBub_ctx_set_option\fP(struct ub_ctx* ctx, char* opt, char* val); +.sp +int \fBub_ctx_get_option\fP(struct ub_ctx* ctx, char* opt, char** val); +.sp +int \fBub_ctx_config\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_set_fwd\fP(struct ub_ctx* ctx, char* addr); +.INDENT 0.0 +.TP +int \fBub_ctx_set_stub\fP(struct ub_ctx* ctx, char* zone, char* addr, +int isprime); +.UNINDENT +.sp +int \fBub_ctx_set_tls\fP(struct ub_ctx* ctx, int tls); +.sp +int \fBub_ctx_resolvconf\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_hosts\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_add_ta\fP(struct ub_ctx* ctx, char* ta); +.sp +int \fBub_ctx_add_ta_autr\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_add_ta_file\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_trustedkeys\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_debugout\fP(struct ub_ctx* ctx, FILE* out); +.sp +int \fBub_ctx_debuglevel\fP(struct ub_ctx* ctx, int d); +.sp +int \fBub_ctx_async\fP(struct ub_ctx* ctx, int dothread); +.sp +int \fBub_poll\fP(struct ub_ctx* ctx); +.sp +int \fBub_wait\fP(struct ub_ctx* ctx); +.sp +int \fBub_fd\fP(struct ub_ctx* ctx); +.sp +int \fBub_process\fP(struct ub_ctx* ctx); +.INDENT 0.0 +.TP +int \fBub_resolve\fP(struct ub_ctx* ctx, char* name, +int rrtype, int rrclass, struct ub_result** result); +.TP +int \fBub_resolve_async\fP(struct ub_ctx* ctx, char* name, +int rrtype, int rrclass, void* mydata, +ub_callback_type* callback, int* async_id); +.UNINDENT +.sp +int \fBub_cancel\fP(struct ub_ctx* ctx, int async_id); +.sp +void \fBub_resolve_free\fP(struct ub_result* result); +.sp +const char * \fBub_strerror\fP(int err); +.sp +int \fBub_ctx_print_local_zones\fP(struct ub_ctx* ctx); +.sp +int \fBub_ctx_zone_add\fP(struct ub_ctx* ctx, char* zone_name, char* zone_type); +.sp +int \fBub_ctx_zone_remove\fP(struct ub_ctx* ctx, char* zone_name); +.sp +int \fBub_ctx_data_add\fP(struct ub_ctx* ctx, char* data); +.sp +int \fBub_ctx_data_remove\fP(struct ub_ctx* ctx, char* data); +.SH DESCRIPTION +.sp +Unbound is an implementation of a DNS resolver, that does caching and DNSSEC +validation. +This is the library API, for using the \fB\-lunbound\fP library. +The server daemon is described in \fI\%unbound(8)\fP\&. +The library works independent from a running unbound server, and 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. +.sp +The library uses a variable of type \fIstruct ub_ctx\fP to keep context between +calls. +The user must maintain it, creating it with \fBub_ctx_create\fP and deleting it +with \fBub_ctx_delete\fP\&. +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. +.sp +The functions are thread\-safe, and a context can 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. +.sp The functions are discussed in turn below. -.SH "FUNCTIONS" -.TP +.SH FUNCTIONS +.INDENT 0.0 +.TP .B 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 -.B ub_ctx_resolvconf -and -.B ub_ctx_hosts -to read them. -Before you call this, use the openssl functions CRYPTO_set_id_callback and -CRYPTO_set_locking_callback to set up asynchronous operation if you use -lib openssl (the application calls these functions once for initialisation). -Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function. +The information from \fB/etc/resolv.conf\fP and \fB/etc/hosts\fP is +not utilised by default. +Use \fBub_ctx_resolvconf\fP and \fBub_ctx_hosts\fP to read them. +Before you call this, use the openssl functions +\fBCRYPTO_set_id_callback\fP and \fBCRYPTO_set_locking_callback\fP to set +up asynchronous operation if you use lib openssl (the application calls +these functions once for initialisation). +Openssl 1.0.0 or later uses the \fBCRYPTO_THREADID_set_callback\fP +function. .TP .B ub_ctx_delete Delete validation context and free associated resources. -Outstanding async queries are killed and callbacks are not called for them. +Outstanding async queries are killed and callbacks are not called for +them. .TP .B ub_ctx_set_option -A power\-user interface that lets you specify one of the options from the -config file format, see \fIunbound.conf\fR(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 ':'. +A power\-user interface that lets you specify one of the options from +the config file format, see \fI\%unbound.conf(5)\fP\&. +Not all options are relevant. +For some specific options, such as adding trust anchors, special +routines exist. +Pass the option name with the trailing \fB\(aq:\(aq\fP\&. .TP .B 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. +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 \fB\(aq:\(aq\fP\&. +The returned value must be free(2)d by the caller. .TP .B ub_ctx_config -A power\-user interface that lets you specify an unbound config file, see -\fIunbound.conf\fR(5), which is read for configuration. Not all options are -relevant. For some specific options, such as adding trust anchors, special -routines exist. This function is thread\-safe only if a single instance of -ub_ctx* exists in the application. If several instances exist the -application has to ensure that ub_ctx_config is not called in parallel by -the different instances. +A power\-user interface that lets you specify an unbound config file, +see \fI\%unbound.conf(5)\fP, which is read for +configuration. +Not all options are relevant. +For some specific options, such as adding trust anchors, special +routines exist. +This function is thread\-safe only if a single instance of \fBub_ctx\fP* +exists in the application. +If several instances exist the application has to ensure that +\fBub_ctx_config\fP is not called in parallel by the different instances. .TP .B 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. +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. .TP .B ub_ctx_set_stub -Set a stub zone, authoritative dns servers to use for a particular zone. -IP4 or IP6 address. If the address is NULL the stub entry is removed. -Set isprime true if you configure root hints with it. Otherwise similar to -the stub zone item from unbound's config file. Can be called several times, -for different zones, or to add multiple addresses for a particular zone. -At this time it is only possible to set configuration before the -first resolve is done. +Set a stub zone, authoritative dns servers to use for a particular +zone. +IP4 or IP6 address. +If the address is NULL the stub entry is removed. +Set isprime true if you configure root hints with it. +Otherwise similar to the stub zone item from unbound\(aqs config file. +Can be called several times, for different zones, or to add multiple +addresses for a particular zone. +At this time it is only possible to set configuration before the first +resolve is done. .TP .B ub_ctx_set_tls -Enable DNS over TLS (DoT) for machines set with -.B ub_ctx_set_fwd. -At this time it is only possible to set configuration before the -first resolve is done. +Enable DNS over TLS (DoT) for machines set with \fBub_ctx_set_fwd\fP\&. +At this time it is only possible to set configuration before the first +resolve is done. .TP .B 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. +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 \fB\(dq/etc/resolv.conf\(dq\fP\&. +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 \fIresolv.conf\fR(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. +settings from \fIresolv.conf(5)\fP are ignored. +If fname NULL is passed, \fB\(dq/etc/resolv.conf\(dq\fP 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. .TP .B 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. -.TP -.B -ub_ctx_add_ta +Usually \fB\(dq/etc/hosts\(dq\fP\&. +When queried for, these addresses are not marked DNSSEC secure. +If fname NULL is passed, \fB\(dq/etc/hosts\(dq\fP is used (if on Windows, +\fBetc/hosts\fP from WINDIR is picked instead). +At this time it is only possible to set configuration before the first +resolve is done. +.TP +.B 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. +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. +\fB[domainname]\fP \fB[type]\fP \fB[rdata contents]\fP\&. +Both DS and DNSKEY records are accepted. .TP .B ub_ctx_add_ta_autr -Add filename with automatically tracked trust anchor to the given context. -Pass name of a file with the managed trust anchor. You can create this -file with \fIunbound\-anchor\fR(8) for the root anchor. You can also -create it with an initial file with one line with a DNSKEY or DS record. +Add filename with automatically tracked trust anchor to the given +context. +Pass name of a file with the managed trust anchor. +You can create this file with +\fI\%unbound\-anchor(8)\fP for the root anchor. +You can also create it with an initial file with one line with a DNSKEY +or DS record. If the file is writable, it is updated when the trust anchor changes. -At this time it is only possible to add trusted keys before the -first resolve is done. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B 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. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B 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. +Pass the name of a bind\-style config file with \fBtrusted\-keys{}\fP\&. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B 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. +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. .TP .B ub_ctx_debuglevel -Set debug verbosity for the context. Output is directed to stderr. +Set debug verbosity for the context. +Output is directed to stderr. Higher debug level gives more output. .TP .B ub_ctx_async Set a context behaviour for asynchronous action. -if set to true, enables threading and a call to -.B ub_resolve_async +if set to true, enables threading and a call to \fBub_resolve_async\fP 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 -.B ub_resolve_async -calls have been made have no effect (delete and re\-create the context -to change). +Changes to this setting after \fBub_resolve_async\fP calls have been made +have no effect (delete and re\-create the context to change). .TP .B 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. +Do not poll in a loop, instead extract the \fBfd\fP 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 -.B ub_process -to do callbacks. +If nonzero, call \fBub_process\fP to do callbacks. .TP .B ub_wait -Wait for a context to finish with results. Calls -.B ub_process -after the wait for you. After the wait, there are no more outstanding -asynchronous queries. +Wait for a context to finish with results. +Calls \fBub_process\fP after the wait for you. +After the wait, there are no more outstanding asynchronous queries. .TP .B 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 \fBub_process\fR to continue processing. +Get file descriptor. +Wait for it to become readable, at this point answers are returned from +the asynchronous validating resolver. +Then call the \fBub_process\fP to continue processing. .TP .B ub_process Call this routine to continue processing results from the validating -resolver (when the fd becomes readable). +resolver (when the \fBfd\fP becomes readable). Will perform necessary callbacks. .TP .B ub_resolve @@ -340,95 +311,111 @@ The result structure is newly allocated with the resulting data. .TP .B ub_resolve_async Perform asynchronous resolution and validation of the target name. -Arguments mean the same as for \fBub_resolve\fR 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 -.IP -void my_callback_function(void* my_arg, int err, -.br - struct ub_result* result); -.IP -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. +Arguments mean the same as for \fBub_resolve\fP 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: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +void my_callback_function(void* my_arg, int err, + struct ub_result* result); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBasync_id\fP 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 \fBasync_id\fP is not returned. .TP .B 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. +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. .TP .B ub_resolve_free -Free struct ub_result contents after use. +Free struct \fBub_result\fP contents after use. .TP .B ub_strerror -Convert error value from one of the unbound library functions -to a human readable string. +Convert error value from one of the unbound library functions to a +human readable string. .TP .B ub_ctx_print_local_zones Debug printout the local authority information to debug output. .TP .B ub_ctx_zone_add -Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) -statement. +Add new zone to local authority info, like local\-zone +\fI\%unbound.conf(5)\fP statement. .TP .B ub_ctx_zone_remove Delete zone from local authority info. .TP .B ub_ctx_data_add Add resource record data to local authority info, like local\-data -\fIunbound.conf\fR(5) statement. +\fI\%unbound.conf(5)\fP statement. .TP .B ub_ctx_data_remove Delete local authority data from the name given. -.SH "RESULT DATA STRUCTURE" -The result of the DNS resolution and validation is returned as -\fIstruct ub_result\fR. The result structure contains the following entries. -.P +.UNINDENT +.SH RESULT DATA STRUCTURE +.sp +The result of the DNS resolution and validation is returned as \fIstruct +ub_result\fP\&. +The result structure contains the following entries: +.INDENT 0.0 +.INDENT 3.5 +.sp .nf - 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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ - int ttl; /* number of seconds the result is valid */ - }; +.ft C +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 was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ + int ttl; /* number of seconds the result is valid */ +}; +.ft P .fi -.P -If both secure and bogus are false, security was not enabled for the -domain of the query. Else, they are not both true, one of them is true. -.SH "RETURN VALUES" -Many routines return an error code. The value 0 (zero) denotes no error -happened. Other values can be passed to -.B ub_strerror -to obtain a readable error string. -.B ub_strerror -returns a zero terminated string. -.B ub_ctx_create -returns NULL on an error (a malloc failure). -.B ub_poll -returns true if some information may be available, false otherwise. -.B ub_fd -returns a file descriptor or \-1 on error. -.B ub_ctx_config -and -.B ub_ctx_resolvconf -attempt to leave errno informative on a function return with file read failure. -.SH "SEE ALSO" -\fIunbound.conf\fR(5), -\fIunbound\fR(8). -.SH "AUTHORS" -.B Unbound -developers are mentioned in the CREDITS file in the distribution. +.UNINDENT +.UNINDENT +.sp +If both secure and bogus are false, security was not enabled for the domain of +the query. +Else, they are not both true, one of them is true. +.SH RETURN VALUES +.sp +Many routines return an error code. +The value 0 (zero) denotes no error happened. +Other values can be passed to \fBub_strerror\fP to obtain a readable error +string. +\fBub_strerror\fP returns a zero terminated string. +\fBub_ctx_create\fP returns NULL on an error (a malloc failure). +\fBub_poll\fP returns true if some information may be available, false otherwise. +\fBub_fd\fP returns a file descriptor or \-1 on error. +\fBub_ctx_config\fP and \fBub_ctx_resolvconf\fP attempt to leave errno informative +on a function return with file read failure. +.SH SEE ALSO +.sp +\fI\%unbound.conf(5)\fP, \fI\%unbound(8)\fP\&. +.SH AUTHOR +Unbound developers are mentioned in the CREDITS file in the distribution. +.SH COPYRIGHT +1999-2025, NLnet Labs +.\" Generated by docutils manpage writer. +. |