ares_init_options.3 (14976B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" Copyright (C) 2004-2010 by Daniel Stenberg 4 .\" 5 .\" SPDX-License-Identifier: MIT 6 .\" 7 .TH ARES_INIT_OPTIONS 3 "5 March 2010" 8 .SH NAME 9 ares_init_options, ares_init \- Initialize a resolver channel 10 .SH SYNOPSIS 11 .nf 12 #include <ares.h> 13 14 struct ares_server_failover_options { 15 unsigned short retry_chance; 16 size_t retry_delay; 17 }; 18 19 struct ares_options { 20 int flags; 21 int timeout; /* in seconds or milliseconds, depending on options */ 22 int tries; 23 int ndots; 24 unsigned short udp_port; 25 unsigned short tcp_port; 26 int socket_send_buffer_size; 27 int socket_receive_buffer_size; 28 struct in_addr *servers; 29 int nservers; 30 char **domains; 31 int ndomains; 32 char *lookups; 33 ares_sock_state_cb sock_state_cb; 34 void *sock_state_cb_data; 35 struct apattern *sortlist; 36 int nsort; 37 int ednspsz; 38 char *resolvconf_path; 39 char *hosts_path; 40 int udp_max_queries; 41 int maxtimeout; /* in milliseconds */ 42 unsigned int qcache_max_ttl; /* in seconds */ 43 ares_evsys_t evsys; 44 struct ares_server_failover_options server_failover_opts; 45 }; 46 47 int ares_init_options(ares_channel_t **\fIchannelptr\fP, 48 const struct ares_options *\fIoptions\fP, 49 int \fIoptmask\fP); 50 51 int ares_init(ares_channel_t **\fIchannelptr\fP); 52 53 .fi 54 .SH DESCRIPTION 55 The \fBares_init(3)\fP function is equivalent to calling 56 \fBares_init_options(channelptr, NULL, 0)\fP. It is recommended to use 57 \fBares_init_options(3)\fP instead and to set or make configurable the 58 appropriate options for your application. 59 60 The \fBares_init_options(3)\fP function initializes a communications channel 61 for name service lookups. If it returns successfully, 62 \fBares_init_options(3)\fP will set the variable pointed to by 63 \fIchannelptr\fP to a handle used to identify the name service channel. The 64 caller should invoke \fIares_destroy(3)\fP on the handle when the channel is 65 no longer needed. 66 67 It is recommended for an application to have at most one ares channel and use 68 this for all DNS queries for the life of the application. When system 69 configuration changes, \fIares_reinit(3)\fP can be called to reload the 70 configuration if necessary. The recommended concurrent query limit is about 71 32k queries, but remembering that when specifying AF_UNSPEC for 72 \fBares_getaddrinfo(3)\fP or \fBares_gethostbyname(3)\fP, they may spawn 73 2 queries internally. The reason for the limit is c-ares does not allow 74 duplicate DNS query ids (which have a maximum of 64k) to be oustanding at a 75 given time, and it must randomly search for an available id thus 32k will limit 76 the number of searches. This limitation should not be a concern for most 77 implementations and c-ares may implement queuing in future releases to lift this 78 limitation. 79 80 The \fIoptmask\fP parameter generally specifies which fields in the structure pointed to 81 by \fIoptions\fP are set, as follows: 82 .TP 18 83 .B ARES_OPT_FLAGS 84 .B int \fIflags\fP; 85 .br 86 Flags controlling the behavior of the resolver: 87 .RS 4 88 .TP 23 89 .B ARES_FLAG_USEVC 90 Always use TCP queries (the "virtual circuit") instead of UDP 91 queries. Normally, TCP is only used if a UDP query yields a truncated 92 result. 93 .TP 23 94 .B ARES_FLAG_PRIMARY 95 Only query the first server in the list of servers to query. 96 .TP 23 97 .B ARES_FLAG_IGNTC 98 If a truncated response to a UDP query is received, do not fall back 99 to TCP; simply continue on with the truncated response. 100 .TP 23 101 .B ARES_FLAG_NORECURSE 102 Do not set the "recursion desired" bit on outgoing queries, so that the name 103 server being contacted will not try to fetch the answer from other servers if 104 it doesn't know the answer locally. Be aware that ares will not do the 105 recursion for you. Recursion must be handled by the application calling ares 106 if \fIARES_FLAG_NORECURSE\fP is set. 107 .TP 23 108 .B ARES_FLAG_STAYOPEN 109 Do not close communications sockets when the number of active queries 110 drops to zero. 111 .TP 23 112 .B ARES_FLAG_NOSEARCH 113 Do not use the default search domains; only query hostnames as-is or 114 as aliases. 115 .TP 23 116 .B ARES_FLAG_NOALIASES 117 Do not honor the HOSTALIASES environment variable, which normally 118 specifies a file of hostname translations. 119 .TP 23 120 .B ARES_FLAG_NOCHECKRESP 121 Do not discard responses with the SERVFAIL, NOTIMP, or REFUSED 122 response code or responses whose questions don't match the questions 123 in the request. Primarily useful for writing clients which might be 124 used to test or debug name servers. 125 .TP 23 126 .B ARES_FLAG_EDNS 127 Include an EDNS pseudo-resource record (RFC 2671) in generated requests. As of 128 v1.22, this is on by default if flags are otherwise not set. 129 .TP 23 130 .B ARES_FLAG_NO_DFLT_SVR 131 Do not attempt to add a default local named server if there are no other 132 servers available. Instead, fail initialization with \fIARES_ENOSERVER\fP. 133 .TP 23 134 .B ARES_FLAG_DNS0x20 135 Enable support for DNS 0x20 as per https://datatracker.ietf.org/doc/html/draft-vixie-dnsext-dns0x20-00 136 which adds additional entropy to the request by randomizing the case of the 137 query name. Integrators need to ensure they treat DNS name responses as 138 case-insensitive. In rare circumstances this may cause the inability to lookup 139 certain domains if the upstream server or the authoritative server for the 140 domain is non-compliant. 141 .RE 142 .TP 18 143 .B ARES_OPT_TIMEOUT 144 .B int \fItimeout\fP; 145 .br 146 The number of seconds each name server is given to respond to a query on the 147 first try. See \fIARES_OPT_TIMEOUTMS\fP which this value is converted into. 148 .TP 18 149 .B ARES_OPT_TIMEOUTMS 150 .B int \fItimeout\fP; 151 .br 152 The number of milliseconds each name server is given to respond to a query on 153 the first try of any given server. The default is two seconds, however any 154 value below 250ms will automatically be set to 250ms (roughly the RTT half-way 155 around the world). Note that this option is specified with the same struct field 156 as the former \fIARES_OPT_TIMEOUT\fP, it is but the option bits that tell c-ares 157 how to interpret the number. This option was added in c-ares 1.5.2. 158 159 As of c-ares 1.32.0, this option is only honored on the first successful query 160 to any given server, after that the timeout is automatically calculated based 161 on prior query history. 162 .TP 18 163 .B ARES_OPT_TRIES 164 .B int \fItries\fP; 165 .br 166 The number of tries the resolver will try contacting each name server 167 before giving up. The default is three tries. 168 .TP 18 169 .B ARES_OPT_NDOTS 170 .B int \fIndots\fP; 171 .br 172 The number of dots which must be present in a domain name for it to be 173 queried for "as is" prior to querying for it with the default domain 174 extensions appended. The default value is 1 unless set otherwise by 175 resolv.conf or the RES_OPTIONS environment variable. Valid range is 0-15. 176 .TP 18 177 .B ARES_OPT_MAXTIMEOUTMS 178 .B int \fImaxtimeout\fP; 179 .br 180 The upper bound for timeout between sequential retry attempts. When retrying 181 queries, the timeout is increased from the requested timeout parameter, this 182 caps the value. 183 .TP 18 184 .B ARES_OPT_UDP_PORT 185 .B unsigned short \fIudp_port\fP; 186 .br 187 The port to use for queries over UDP, in host byte order. 188 The default value is 53, the standard name service port. 189 .TP 18 190 .B ARES_OPT_TCP_PORT 191 .B unsigned short \fItcp_port\fP; 192 .br 193 The port to use for queries over TCP, in host byte order. 194 The default value is 53, the standard name service port. 195 .TP 18 196 .B ARES_OPT_SERVERS 197 .B struct in_addr *\fIservers\fP; 198 .br 199 .B int \fInservers\fP; 200 .br 201 The list of IPv4 servers to contact, instead of the servers specified in 202 resolv.conf or the local named. In order to allow specification of either IPv4 203 or IPv6 name servers, the \Bares_set_servers(3)\fP function must be used 204 instead. 205 .TP 18 206 .B ARES_OPT_DOMAINS 207 .B char **\fIdomains\fP; 208 .br 209 .B int \fIndomains\fP; 210 .br 211 The domains to search, instead of the domains specified in resolv.conf 212 or the domain derived from the kernel hostname variable. 213 .TP 18 214 .B ARES_OPT_LOOKUPS 215 .B char *\fIlookups\fP; 216 .br 217 The lookups to perform for host queries. 218 .I lookups 219 should be set to a string of the characters "b" or "f", where "b" 220 indicates a DNS lookup and "f" indicates a lookup in the hosts file. 221 .TP 18 222 .B ARES_OPT_SOCK_STATE_CB 223 .B void (*\fIsock_state_cb\fP)(void *data, ares_socket_t socket_fd, int readable, int writable); 224 .br 225 .B void *\fIsock_state_cb_data\fP; 226 .br 227 A callback function to be invoked when a socket changes state. 228 .I socket_fd 229 will be passed the socket whose state has changed; 230 .I readable 231 will be set to true if the socket should listen for read events, and 232 .I writable 233 will be set to true if the socket should listen for write events. 234 The value of 235 .I sock_state_cb_data 236 will be passed as the 237 .I data 238 argument. The channel lock is held during this callback, if in a multithreaded 239 application, care must be taken to ensure lock order is correct to be able to 240 handle this and avoid deadlocks. 241 242 Cannot be used with \fBARES_OPT_EVENT_THREAD\fP. 243 .TP 18 244 .B ARES_OPT_SORTLIST 245 .B struct apattern *\fIsortlist\fP; 246 .br 247 .B int \fInsort\fP; 248 .br 249 A list of IP address ranges that specifies the order of preference that 250 results from \fIares_gethostbyname\fP should be returned in. Note that 251 this can only be used with a sortlist retrieved via 252 \fBares_save_options(3)\fP (because 253 .B struct apattern 254 is opaque); to set a fresh sort list, use \fBares_set_sortlist(3)\fP. 255 .TP 18 256 .B ARES_OPT_SOCK_SNDBUF 257 .B int \fIsocket_send_buffer_size\fP; 258 .br 259 The send buffer size to set for the socket. 260 .TP 18 261 .B ARES_OPT_SOCK_RCVBUF 262 .B int \fIsocket_receive_buffer_size\fP; 263 .br 264 The receive buffer size to set for the socket. 265 .TP 18 266 .B ARES_OPT_EDNSPSZ 267 .B int \fIednspsz\fP; 268 .br 269 The message size to be advertised in EDNS; only takes effect if the 270 .B ARES_FLAG_EDNS 271 flag is set. Defaults to 1232, the recommended size. 272 .TP 18 273 .B ARES_OPT_RESOLVCONF 274 .B char *\fIresolvconf_path\fP; 275 .br 276 The path to use for reading the resolv.conf file. The 277 .I resolvconf_path 278 should be set to a path string, and will be honoured on *nix like systems. The 279 default is 280 .B /etc/resolv.conf 281 .br 282 .TP 18 283 .B ARES_OPT_HOSTS_FILE 284 .B char *\fIhosts_path\fP; 285 .br 286 The path to use for reading the hosts file. The 287 .I hosts_path 288 should be set to a path string, and will be honoured on *nix like systems. The 289 default is 290 .B /etc/hosts 291 .br 292 .TP 18 293 .B ARES_OPT_UDP_MAX_QUERIES 294 .B int \fIudp_max_queries\fP; 295 .br 296 The maximum number of udp queries that can be sent on a single ephemeral port 297 to a given DNS server before a new ephemeral port is assigned. Any value of 0 298 or less will be considered unlimited, and is the default. 299 .br 300 .TP 18 301 .B ARES_OPT_QUERY_CACHE 302 .B unsigned int \fIqcache_max_ttl\fP; 303 .br 304 As of c-ares 1.31.0, the query cache is enabled by default with a TTL of 1hr. 305 To disable the query cache, specify this option with a TTL of 0. The query 306 cache is based on the returned TTL in the DNS message. Only fully successful 307 and NXDOMAIN query results will be cached. Fill in the \fIqcache_max_ttl\fP 308 with the maximum number of seconds a query result may be cached which will 309 override a larger TTL in the response message. This must be a non-zero value 310 otherwise the cache will be disabled. Choose a reasonable value for your 311 application such as 300 (5 minutes) or 3600 (1 hour). The query cache is 312 automatically flushed if a server configuration change is made. 313 .br 314 .TP 18 315 .B ARES_OPT_EVENT_THREAD 316 .B ares_evsys_t \fIevsys\fP; 317 .br 318 Enable the built-in event thread (Recommended). Introduced in c-ares 1.26.0. 319 Set the \fIevsys\fP parameter to \fBARES_EVSYS_DEFAULT\fP (0). Other values are 320 reserved for testing and should not be used by integrators. 321 322 This option cannot be used with the \fBARES_OPT_SOCK_STATE_CB\fP option, nor the 323 \fIares_set_socket_functions(3)\fP or 324 \fIares_set_socket_configure_callback(3)\fP functions. 325 326 When enabled, the integrator is no longer responsible for notifying c-ares of 327 any events on the file descriptors, so \fIares_process(3)\fP nor 328 \fIares_process_fd(3)\fP should ever be called when this option is enabled. 329 330 As of c-ares 1.29.0, when enabled, it will also automatically re-load the 331 system configuration when changes are detected. 332 333 Use \fIares_threadsafety(3)\fP to determine if this option is available to be 334 used. 335 336 Returns \fBARES_ENOTIMP\fP if this option is passed but not available, and 337 \fBARES_ESERVFAIL\fP if there is a critical failure during initialization of 338 the event thread. 339 .br 340 .TP 18 341 .B ARES_OPT_SERVER_FAILOVER 342 .B struct ares_server_failover_options \fIserver_failover_opts\fP; 343 .br 344 Configure server failover retry behavior. When a DNS server fails to 345 respond to a query, c-ares will deprioritize the server. On subsequent 346 queries, servers with fewer consecutive failures will be selected in 347 preference. However, in order to detect when such a server has recovered, 348 c-ares will occasionally retry failed servers by probing with a copy of 349 the query, without affecting the latency of the actual requested query. The 350 \fIares_server_failover_options\fP structure contains options to control this 351 behavior. 352 The \fIretry_chance\fP field gives the probability (1/N) of retrying a 353 failed server on any given query. Setting to a value of 0 disables retries. 354 The \fIretry_delay\fP field gives the minimum delay in milliseconds that c-ares 355 will wait before retrying a specific failed server. 356 If this option is not specificed then c-ares will use a probability of 10% 357 and a minimum delay of 5 seconds. 358 .br 359 .PP 360 The \fIoptmask\fP parameter also includes options without a corresponding 361 field in the 362 .B ares_options 363 structure, as follows: 364 .TP 23 365 .B ARES_OPT_ROTATE 366 Perform round-robin selection of the nameservers configured for the channel 367 for each resolution. 368 .TP 23 369 .B ARES_OPT_NOROTATE 370 Do not perform round-robin nameserver selection; always use the list of 371 nameservers in the same order. The default is not to rotate servers, however 372 the system configuration can specify the desire to rotate and this 373 configuration value can negate such a system configuration. 374 .PP 375 376 .SH RETURN VALUES 377 \fBares_init_options(3)\fP and \fBares_init(3)\fP can return any of the 378 following values: 379 .TP 14 380 .B ARES_SUCCESS 381 Initialization succeeded. 382 .TP 14 383 .B ARES_EFILE 384 A configuration file could not be read. 385 .TP 14 386 .B ARES_ENOMEM 387 The process's available memory was exhausted. 388 .TP 14 389 .B ARES_ENOTINITIALIZED 390 c-ares library initialization not yet performed. 391 .TP 14 392 .B ARES_ENOSERVER 393 No DNS servers were available to use. 394 .SH NOTES 395 When initializing from 396 .B /etc/resolv.conf, 397 (or, alternatively when specified by the 398 .I resolvconf_path 399 path location) 400 \fBares_init_options(3)\fP and \fBares_init(3)\fP reads the \fIdomain\fP and 401 \fIsearch\fP directives to allow lookups of short names relative to the domains 402 specified. The \fIdomain\fP and \fIsearch\fP directives override one another. 403 If more than one instance of either \fIdomain\fP or \fIsearch\fP directives is 404 specified, the last occurrence wins. For more information, please see the 405 .BR resolv.conf (5) 406 manual page. 407 .SH SEE ALSO 408 .BR ares_reinit (3), 409 .BR ares_destroy (3), 410 .BR ares_dup (3), 411 .BR ares_library_init (3), 412 .BR ares_save_options (3), 413 .BR ares_set_servers (3), 414 .BR ares_set_sortlist (3), 415 .BR ares_threadsafety (3)