1.TH "libunbound" "3" "Mar 21, 2013" "NLnet Labs" "unbound 1.4.20"
| 1.TH "libunbound" "3" "Mar 12, 2014" "NLnet Labs" "unbound 1.4.22"
|
2.\" 3.\" libunbound.3 -- unbound library functions manual 4.\" 5.\" Copyright (c) 2007, NLnet Labs. All rights reserved. 6.\" 7.\" See LICENSE for the license. 8.\" 9.\" 10.SH "NAME" 11.LP 12.B libunbound, 13.B unbound.h, 14.B ub_ctx, 15.B ub_result, 16.B ub_callback_t, 17.B ub_ctx_create, 18.B ub_ctx_delete, 19.B ub_ctx_set_option, 20.B ub_ctx_get_option, 21.B ub_ctx_config, 22.B ub_ctx_set_fwd, 23.B ub_ctx_resolvconf, 24.B ub_ctx_hosts, 25.B ub_ctx_add_ta, 26.B ub_ctx_add_ta_file, 27.B ub_ctx_trustedkeys, 28.B ub_ctx_debugout, 29.B ub_ctx_debuglevel, 30.B ub_ctx_async, 31.B ub_poll, 32.B ub_wait, 33.B ub_fd, 34.B ub_process, 35.B ub_resolve, 36.B ub_resolve_async, 37.B ub_cancel, 38.B ub_resolve_free, 39.B ub_strerror, 40.B ub_ctx_print_local_zones, 41.B ub_ctx_zone_add, 42.B ub_ctx_zone_remove, 43.B ub_ctx_data_add, 44.B ub_ctx_data_remove
| 2.\" 3.\" libunbound.3 -- unbound library functions manual 4.\" 5.\" Copyright (c) 2007, NLnet Labs. All rights reserved. 6.\" 7.\" See LICENSE for the license. 8.\" 9.\" 10.SH "NAME" 11.LP 12.B libunbound, 13.B unbound.h, 14.B ub_ctx, 15.B ub_result, 16.B ub_callback_t, 17.B ub_ctx_create, 18.B ub_ctx_delete, 19.B ub_ctx_set_option, 20.B ub_ctx_get_option, 21.B ub_ctx_config, 22.B ub_ctx_set_fwd, 23.B ub_ctx_resolvconf, 24.B ub_ctx_hosts, 25.B ub_ctx_add_ta, 26.B ub_ctx_add_ta_file, 27.B ub_ctx_trustedkeys, 28.B ub_ctx_debugout, 29.B ub_ctx_debuglevel, 30.B ub_ctx_async, 31.B ub_poll, 32.B ub_wait, 33.B ub_fd, 34.B ub_process, 35.B ub_resolve, 36.B ub_resolve_async, 37.B ub_cancel, 38.B ub_resolve_free, 39.B ub_strerror, 40.B ub_ctx_print_local_zones, 41.B ub_ctx_zone_add, 42.B ub_ctx_zone_remove, 43.B ub_ctx_data_add, 44.B ub_ctx_data_remove
|
45\- Unbound DNS validating resolver 1.4.20 functions.
| 45\- Unbound DNS validating resolver 1.4.22 functions.
|
46.SH "SYNOPSIS" 47.LP 48.B #include <unbound.h> 49.LP 50\fIstruct ub_ctx *\fR 51\fBub_ctx_create\fR(\fIvoid\fR); 52.LP 53\fIvoid\fR 54\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx); 55.LP 56\fIint\fR 57\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val); 58.LP 59\fIint\fR 60\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val); 61.LP 62\fIint\fR 63\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 64.LP 65\fIint\fR 66\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr); 67.LP 68\fIint\fR 69\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 70.LP 71\fIint\fR 72\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 73.LP 74\fIint\fR 75\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta); 76.LP 77\fIint\fR 78\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 79.LP 80\fIint\fR 81\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 82.LP 83\fIint\fR 84\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out); 85.LP 86\fIint\fR 87\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d); 88.LP 89\fIint\fR 90\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread); 91.LP 92\fIint\fR 93\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx); 94.LP 95\fIint\fR 96\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx); 97.LP 98\fIint\fR 99\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx); 100.LP 101\fIint\fR 102\fBub_process\fR(\fIstruct ub_ctx*\fR ctx); 103.LP 104\fIint\fR 105\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, 106.br 107 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result); 108.LP 109\fIint\fR 110\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, 111.br 112 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata, 113.br 114 \fIub_callback_t\fR callback, \fIint*\fR async_id); 115.LP 116\fIint\fR 117\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id); 118.LP 119\fIvoid\fR 120\fBub_resolve_free\fR(\fIstruct ub_result*\fR result); 121.LP 122\fIconst char *\fR 123\fBub_strerror\fR(\fIint\fR err); 124.LP 125\fIint\fR 126\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); 127.LP 128\fIint\fR 129\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); 130.LP 131\fIint\fR 132\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); 133.LP 134\fIint\fR 135\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); 136.LP 137\fIint\fR 138\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); 139.SH "DESCRIPTION" 140.LP 141.B Unbound 142is an implementation of a DNS resolver, that does caching and 143DNSSEC validation. This is the library API, for using the \-lunbound library. 144The server daemon is described in \fIunbound\fR(8). 145The library can be used to convert hostnames to ip addresses, and back, 146and obtain other information from the DNS. The library performs public\-key 147validation of results with DNSSEC. 148.P 149The library uses a variable of type \fIstruct ub_ctx\fR to keep context 150between calls. The user must maintain it, creating it with 151.B ub_ctx_create 152and deleting it with 153.B ub_ctx_delete\fR. 154It can be created and deleted at any time. Creating it anew removes any 155previous configuration (such as trusted keys) and clears any cached results. 156.P 157The functions are thread\-safe, and a context an be used in a threaded (as 158well as in a non\-threaded) environment. Also resolution (and validation) 159can be performed blocking and non\-blocking (also called asynchronous). 160The async method returns from the call immediately, so that processing 161can go on, while the results become available later. 162.P 163The functions are discussed in turn below. 164.SH "FUNCTIONS" 165.TP 166.B ub_ctx_create 167Create a new context, initialised with defaults. 168The information from /etc/resolv.conf and /etc/hosts is not utilised 169by default. Use 170.B ub_ctx_resolvconf 171and 172.B ub_ctx_hosts 173to read them.
| 46.SH "SYNOPSIS" 47.LP 48.B #include <unbound.h> 49.LP 50\fIstruct ub_ctx *\fR 51\fBub_ctx_create\fR(\fIvoid\fR); 52.LP 53\fIvoid\fR 54\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx); 55.LP 56\fIint\fR 57\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val); 58.LP 59\fIint\fR 60\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val); 61.LP 62\fIint\fR 63\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 64.LP 65\fIint\fR 66\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr); 67.LP 68\fIint\fR 69\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 70.LP 71\fIint\fR 72\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 73.LP 74\fIint\fR 75\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta); 76.LP 77\fIint\fR 78\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 79.LP 80\fIint\fR 81\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); 82.LP 83\fIint\fR 84\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out); 85.LP 86\fIint\fR 87\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d); 88.LP 89\fIint\fR 90\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread); 91.LP 92\fIint\fR 93\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx); 94.LP 95\fIint\fR 96\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx); 97.LP 98\fIint\fR 99\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx); 100.LP 101\fIint\fR 102\fBub_process\fR(\fIstruct ub_ctx*\fR ctx); 103.LP 104\fIint\fR 105\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, 106.br 107 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result); 108.LP 109\fIint\fR 110\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, 111.br 112 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata, 113.br 114 \fIub_callback_t\fR callback, \fIint*\fR async_id); 115.LP 116\fIint\fR 117\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id); 118.LP 119\fIvoid\fR 120\fBub_resolve_free\fR(\fIstruct ub_result*\fR result); 121.LP 122\fIconst char *\fR 123\fBub_strerror\fR(\fIint\fR err); 124.LP 125\fIint\fR 126\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); 127.LP 128\fIint\fR 129\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); 130.LP 131\fIint\fR 132\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); 133.LP 134\fIint\fR 135\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); 136.LP 137\fIint\fR 138\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); 139.SH "DESCRIPTION" 140.LP 141.B Unbound 142is an implementation of a DNS resolver, that does caching and 143DNSSEC validation. This is the library API, for using the \-lunbound library. 144The server daemon is described in \fIunbound\fR(8). 145The library can be used to convert hostnames to ip addresses, and back, 146and obtain other information from the DNS. The library performs public\-key 147validation of results with DNSSEC. 148.P 149The library uses a variable of type \fIstruct ub_ctx\fR to keep context 150between calls. The user must maintain it, creating it with 151.B ub_ctx_create 152and deleting it with 153.B ub_ctx_delete\fR. 154It can be created and deleted at any time. Creating it anew removes any 155previous configuration (such as trusted keys) and clears any cached results. 156.P 157The functions are thread\-safe, and a context an be used in a threaded (as 158well as in a non\-threaded) environment. Also resolution (and validation) 159can be performed blocking and non\-blocking (also called asynchronous). 160The async method returns from the call immediately, so that processing 161can go on, while the results become available later. 162.P 163The functions are discussed in turn below. 164.SH "FUNCTIONS" 165.TP 166.B ub_ctx_create 167Create a new context, initialised with defaults. 168The information from /etc/resolv.conf and /etc/hosts is not utilised 169by default. Use 170.B ub_ctx_resolvconf 171and 172.B ub_ctx_hosts 173to read them.
|
| 174Before you call this, use the openssl functions CRYPTO_set_id_callback and 175CRYPTO_set_locking_callback to set up asyncronous operation if you use 176lib openssl (the application calls these functions once for initialisation).
|
174.TP 175.B ub_ctx_delete 176Delete validation context and free associated resources. 177Outstanding async queries are killed and callbacks are not called for them. 178.TP 179.B ub_ctx_set_option 180A power\-user interface that lets you specify one of the options from the 181config file format, see \fIunbound.conf\fR(5). Not all options are 182relevant. For some specific options, such as adding trust anchors, special 183routines exist. Pass the option name with the trailing ':'. 184.TP 185.B ub_ctx_get_option 186A power\-user interface that gets an option value. Some options cannot be 187gotten, and others return a newline separated list. Pass the option name 188without trailing ':'. The returned value must be free(2)d by the caller. 189.TP 190.B ub_ctx_config 191A power\-user interface that lets you specify an unbound config file, see 192\fIunbound.conf\fR(5), which is read for configuration. Not all options are 193relevant. For some specific options, such as adding trust anchors, special 194routines exist. 195.TP 196.B ub_ctx_set_fwd 197Set machine to forward DNS queries to, the caching resolver to use. 198IP4 or IP6 address. Forwards all DNS requests to that machine, which 199is expected to run a recursive resolver. If the proxy is not 200DNSSEC capable, validation may fail. Can be called several times, in 201that case the addresses are used as backup servers. 202At this time it is only possible to set configuration before the 203first resolve is done. 204.TP 205.B ub_ctx_resolvconf 206By default the root servers are queried and full resolver mode is used, but 207you can use this call to read the list of nameservers to use from the 208filename given. 209Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. 210If they do not support DNSSEC, validation may fail. 211Only nameservers are picked up, the searchdomain, ndots and other 212settings from \fIresolv.conf\fR(5) are ignored. 213If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows, 214the system\-wide configured nameserver is picked instead). 215At this time it is only possible to set configuration before the 216first resolve is done. 217.TP 218.B ub_ctx_hosts 219Read list of hosts from the filename given. 220Usually "/etc/hosts". When queried for, these addresses are not marked 221DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used 222(if on Windows, etc/hosts from WINDIR is picked instead). 223At this time it is only possible to set configuration before the 224first resolve is done. 225.TP 226.B 227ub_ctx_add_ta 228Add a trust anchor to the given context. 229At this time it is only possible to add trusted keys before the 230first resolve is done. 231The format is a string, similar to the zone\-file format, 232[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted. 233.TP 234.B ub_ctx_add_ta_file 235Add trust anchors to the given context. 236Pass name of a file with DS and DNSKEY records in zone file format. 237At this time it is only possible to add trusted keys before the 238first resolve is done. 239.TP 240.B ub_ctx_trustedkeys 241Add trust anchors to the given context. 242Pass the name of a bind\-style config file with trusted\-keys{}. 243At this time it is only possible to add trusted keys before the 244first resolve is done. 245.TP 246.B ub_ctx_debugout 247Set debug and error log output to the given stream. Pass NULL to disable 248output. Default is stderr. File\-names or using syslog can be enabled 249using config options, this routine is for using your own stream. 250.TP 251.B ub_ctx_debuglevel 252Set debug verbosity for the context. Output is directed to stderr. 253Higher debug level gives more output. 254.TP 255.B ub_ctx_async 256Set a context behaviour for asynchronous action. 257if set to true, enables threading and a call to 258.B ub_resolve_async 259creates a thread to handle work in the background. 260If false, a process is forked to handle work in the background. 261Changes to this setting after 262.B ub_resolve_async 263calls have been made have no effect (delete and re\-create the context 264to change). 265.TP 266.B ub_poll 267Poll a context to see if it has any new results. 268Do not poll in a loop, instead extract the fd below to poll for readiness, 269and then check, or wait using the wait routine. 270Returns 0 if nothing to read, or nonzero if a result is available. 271If nonzero, call 272.B ub_process 273to do callbacks. 274.TP 275.B ub_wait 276Wait for a context to finish with results. Calls 277.B ub_process 278after the wait for you. After the wait, there are no more outstanding 279asynchronous queries. 280.TP 281.B ub_fd 282Get file descriptor. Wait for it to become readable, at this point 283answers are returned from the asynchronous validating resolver. 284Then call the \fBub_process\fR to continue processing. 285.TP 286.B ub_process 287Call this routine to continue processing results from the validating 288resolver (when the fd becomes readable). 289Will perform necessary callbacks. 290.TP 291.B ub_resolve 292Perform resolution and validation of the target name. 293The name is a domain name in a zero terminated text string. 294The rrtype and rrclass are DNS type and class codes. 295The result structure is newly allocated with the resulting data. 296.TP 297.B ub_resolve_async 298Perform asynchronous resolution and validation of the target name. 299Arguments mean the same as for \fBub_resolve\fR except no 300data is returned immediately, instead a callback is called later. 301The callback receives a copy of the mydata pointer, that you can use to pass 302information to the callback. The callback type is a function pointer to 303a function declared as 304.IP 305void my_callback_function(void* my_arg, int err, 306.br 307 struct ub_result* result); 308.IP 309The async_id is returned so you can (at your option) decide to track it 310and cancel the request if needed. If you pass a NULL pointer the async_id 311is not returned. 312.TP 313.B ub_cancel 314Cancel an async query in progress. This may return an error if the query 315does not exist, or the query is already being delivered, in that case you 316may still get a callback for the query. 317.TP 318.B ub_resolve_free 319Free struct ub_result contents after use. 320.TP 321.B ub_strerror 322Convert error value from one of the unbound library functions 323to a human readable string. 324.TP 325.B ub_ctx_print_local_zones 326Debug printout the local authority information to debug output. 327.TP 328.B ub_ctx_zone_add 329Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) 330statement. 331.TP 332.B ub_ctx_zone_remove 333Delete zone from local authority info. 334.TP 335.B ub_ctx_data_add 336Add resource record data to local authority info, like local\-data 337\fIunbound.conf\fR(5) statement. 338.TP 339.B ub_ctx_data_remove 340Delete local authority data from the name given. 341.SH "RESULT DATA STRUCTURE" 342.LP 343The result of the DNS resolution and validation is returned as 344\fIstruct ub_result\fR. The result structure contains the following entries. 345.P 346.nf 347 struct ub_result { 348 char* qname; /* text string, original question */ 349 int qtype; /* type code asked for */ 350 int qclass; /* class code asked for */ 351 char** data; /* array of rdata items, NULL terminated*/ 352 int* len; /* array with lengths of rdata items */ 353 char* canonname; /* canonical name of result */ 354 int rcode; /* additional error code in case of no data */ 355 void* answer_packet; /* full network format answer packet */ 356 int answer_len; /* length of packet in octets */ 357 int havedata; /* true if there is data */ 358 int nxdomain; /* true if nodata because name does not exist */ 359 int secure; /* true if result is secure */ 360 int bogus; /* true if a security failure happened */ 361 char* why_bogus; /* string with error if bogus */ 362 int ttl; /* number of seconds the result is valid */ 363 }; 364.fi 365.P 366If both secure and bogus are false, security was not enabled for the
| 177.TP 178.B ub_ctx_delete 179Delete validation context and free associated resources. 180Outstanding async queries are killed and callbacks are not called for them. 181.TP 182.B ub_ctx_set_option 183A power\-user interface that lets you specify one of the options from the 184config file format, see \fIunbound.conf\fR(5). Not all options are 185relevant. For some specific options, such as adding trust anchors, special 186routines exist. Pass the option name with the trailing ':'. 187.TP 188.B ub_ctx_get_option 189A power\-user interface that gets an option value. Some options cannot be 190gotten, and others return a newline separated list. Pass the option name 191without trailing ':'. The returned value must be free(2)d by the caller. 192.TP 193.B ub_ctx_config 194A power\-user interface that lets you specify an unbound config file, see 195\fIunbound.conf\fR(5), which is read for configuration. Not all options are 196relevant. For some specific options, such as adding trust anchors, special 197routines exist. 198.TP 199.B ub_ctx_set_fwd 200Set machine to forward DNS queries to, the caching resolver to use. 201IP4 or IP6 address. Forwards all DNS requests to that machine, which 202is expected to run a recursive resolver. If the proxy is not 203DNSSEC capable, validation may fail. Can be called several times, in 204that case the addresses are used as backup servers. 205At this time it is only possible to set configuration before the 206first resolve is done. 207.TP 208.B ub_ctx_resolvconf 209By default the root servers are queried and full resolver mode is used, but 210you can use this call to read the list of nameservers to use from the 211filename given. 212Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. 213If they do not support DNSSEC, validation may fail. 214Only nameservers are picked up, the searchdomain, ndots and other 215settings from \fIresolv.conf\fR(5) are ignored. 216If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows, 217the system\-wide configured nameserver is picked instead). 218At this time it is only possible to set configuration before the 219first resolve is done. 220.TP 221.B ub_ctx_hosts 222Read list of hosts from the filename given. 223Usually "/etc/hosts". When queried for, these addresses are not marked 224DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used 225(if on Windows, etc/hosts from WINDIR is picked instead). 226At this time it is only possible to set configuration before the 227first resolve is done. 228.TP 229.B 230ub_ctx_add_ta 231Add a trust anchor to the given context. 232At this time it is only possible to add trusted keys before the 233first resolve is done. 234The format is a string, similar to the zone\-file format, 235[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted. 236.TP 237.B ub_ctx_add_ta_file 238Add trust anchors to the given context. 239Pass name of a file with DS and DNSKEY records in zone file format. 240At this time it is only possible to add trusted keys before the 241first resolve is done. 242.TP 243.B ub_ctx_trustedkeys 244Add trust anchors to the given context. 245Pass the name of a bind\-style config file with trusted\-keys{}. 246At this time it is only possible to add trusted keys before the 247first resolve is done. 248.TP 249.B ub_ctx_debugout 250Set debug and error log output to the given stream. Pass NULL to disable 251output. Default is stderr. File\-names or using syslog can be enabled 252using config options, this routine is for using your own stream. 253.TP 254.B ub_ctx_debuglevel 255Set debug verbosity for the context. Output is directed to stderr. 256Higher debug level gives more output. 257.TP 258.B ub_ctx_async 259Set a context behaviour for asynchronous action. 260if set to true, enables threading and a call to 261.B ub_resolve_async 262creates a thread to handle work in the background. 263If false, a process is forked to handle work in the background. 264Changes to this setting after 265.B ub_resolve_async 266calls have been made have no effect (delete and re\-create the context 267to change). 268.TP 269.B ub_poll 270Poll a context to see if it has any new results. 271Do not poll in a loop, instead extract the fd below to poll for readiness, 272and then check, or wait using the wait routine. 273Returns 0 if nothing to read, or nonzero if a result is available. 274If nonzero, call 275.B ub_process 276to do callbacks. 277.TP 278.B ub_wait 279Wait for a context to finish with results. Calls 280.B ub_process 281after the wait for you. After the wait, there are no more outstanding 282asynchronous queries. 283.TP 284.B ub_fd 285Get file descriptor. Wait for it to become readable, at this point 286answers are returned from the asynchronous validating resolver. 287Then call the \fBub_process\fR to continue processing. 288.TP 289.B ub_process 290Call this routine to continue processing results from the validating 291resolver (when the fd becomes readable). 292Will perform necessary callbacks. 293.TP 294.B ub_resolve 295Perform resolution and validation of the target name. 296The name is a domain name in a zero terminated text string. 297The rrtype and rrclass are DNS type and class codes. 298The result structure is newly allocated with the resulting data. 299.TP 300.B ub_resolve_async 301Perform asynchronous resolution and validation of the target name. 302Arguments mean the same as for \fBub_resolve\fR except no 303data is returned immediately, instead a callback is called later. 304The callback receives a copy of the mydata pointer, that you can use to pass 305information to the callback. The callback type is a function pointer to 306a function declared as 307.IP 308void my_callback_function(void* my_arg, int err, 309.br 310 struct ub_result* result); 311.IP 312The async_id is returned so you can (at your option) decide to track it 313and cancel the request if needed. If you pass a NULL pointer the async_id 314is not returned. 315.TP 316.B ub_cancel 317Cancel an async query in progress. This may return an error if the query 318does not exist, or the query is already being delivered, in that case you 319may still get a callback for the query. 320.TP 321.B ub_resolve_free 322Free struct ub_result contents after use. 323.TP 324.B ub_strerror 325Convert error value from one of the unbound library functions 326to a human readable string. 327.TP 328.B ub_ctx_print_local_zones 329Debug printout the local authority information to debug output. 330.TP 331.B ub_ctx_zone_add 332Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) 333statement. 334.TP 335.B ub_ctx_zone_remove 336Delete zone from local authority info. 337.TP 338.B ub_ctx_data_add 339Add resource record data to local authority info, like local\-data 340\fIunbound.conf\fR(5) statement. 341.TP 342.B ub_ctx_data_remove 343Delete local authority data from the name given. 344.SH "RESULT DATA STRUCTURE" 345.LP 346The result of the DNS resolution and validation is returned as 347\fIstruct ub_result\fR. The result structure contains the following entries. 348.P 349.nf 350 struct ub_result { 351 char* qname; /* text string, original question */ 352 int qtype; /* type code asked for */ 353 int qclass; /* class code asked for */ 354 char** data; /* array of rdata items, NULL terminated*/ 355 int* len; /* array with lengths of rdata items */ 356 char* canonname; /* canonical name of result */ 357 int rcode; /* additional error code in case of no data */ 358 void* answer_packet; /* full network format answer packet */ 359 int answer_len; /* length of packet in octets */ 360 int havedata; /* true if there is data */ 361 int nxdomain; /* true if nodata because name does not exist */ 362 int secure; /* true if result is secure */ 363 int bogus; /* true if a security failure happened */ 364 char* why_bogus; /* string with error if bogus */ 365 int ttl; /* number of seconds the result is valid */ 366 }; 367.fi 368.P 369If both secure and bogus are false, security was not enabled for the
|
367domain of the query.
| 370domain of the query. Else, they are not both true, one of them is true.
|
368.SH "RETURN VALUES" 369Many routines return an error code. The value 0 (zero) denotes no error 370happened. Other values can be passed to 371.B ub_strerror 372to obtain a readable error string. 373.B ub_strerror 374returns a zero terminated string. 375.B ub_ctx_create 376returns NULL on an error (a malloc failure). 377.B ub_poll 378returns true if some information may be available, false otherwise. 379.B ub_fd 380returns a file descriptor or \-1 on error. 381.SH "SEE ALSO" 382\fIunbound.conf\fR(5), 383\fIunbound\fR(8). 384.SH "AUTHORS" 385.B Unbound 386developers are mentioned in the CREDITS file in the distribution.
| 371.SH "RETURN VALUES" 372Many routines return an error code. The value 0 (zero) denotes no error 373happened. Other values can be passed to 374.B ub_strerror 375to obtain a readable error string. 376.B ub_strerror 377returns a zero terminated string. 378.B ub_ctx_create 379returns NULL on an error (a malloc failure). 380.B ub_poll 381returns true if some information may be available, false otherwise. 382.B ub_fd 383returns a file descriptor or \-1 on error. 384.SH "SEE ALSO" 385\fIunbound.conf\fR(5), 386\fIunbound\fR(8). 387.SH "AUTHORS" 388.B Unbound 389developers are mentioned in the CREDITS file in the distribution.
|