1.\" $OpenBSD: res_init.3,v 1.6 2021/11/24 20:06:32 jca Exp $ 2.\" 3.\" Copyright (c) 1985, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: November 24 2021 $ 31.Dt RES_INIT 3 32.Os 33.Sh NAME 34.Nm res_query , 35.Nm res_search , 36.Nm res_mkquery , 37.Nm res_send , 38.Nm res_init , 39.Nm dn_comp , 40.Nm dn_expand 41.Nd resolver routines 42.Sh SYNOPSIS 43.In sys/types.h 44.In netinet/in.h 45.In arpa/nameser.h 46.In resolv.h 47.Ft int 48.Fo res_query 49.Fa "const char *dname" 50.Fa "int class" 51.Fa "int type" 52.Fa "unsigned char *answer" 53.Fa "int anslen" 54.Fc 55.Ft int 56.Fo res_search 57.Fa "const char *dname" 58.Fa "int class" 59.Fa "int type" 60.Fa "unsigned char *answer" 61.Fa "int anslen" 62.Fc 63.Ft int 64.Fo res_mkquery 65.Fa "int op" 66.Fa "const char *dname" 67.Fa "int class" 68.Fa "int type" 69.Fa "const unsigned char *data" 70.Fa "int datalen" 71.Fa "const unsigned char *newrr" 72.Fa "unsigned char *buf" 73.Fa "int buflen" 74.Fc 75.Ft int 76.Fo res_send 77.Fa "const unsigned char *msg" 78.Fa "int msglen" 79.Fa "unsigned char *answer" 80.Fa "int anslen" 81.Fc 82.Ft int 83.Fn res_init "void" 84.Ft int 85.Fo dn_comp 86.Fa "const char *exp_dn" 87.Fa "unsigned char *comp_dn" 88.Fa "int length" 89.Fa "unsigned char **dnptrs" 90.Fa "unsigned char **lastdnptr" 91.Fc 92.Ft int 93.Fo dn_expand 94.Fa "const unsigned char *msg" 95.Fa "const unsigned char *eomorig" 96.Fa "const unsigned char *comp_dn" 97.Fa "char *exp_dn" 98.Fa "int length" 99.Fc 100.Sh DESCRIPTION 101These routines are used for making, sending, and interpreting 102query and reply messages with Internet domain name servers. 103.Pp 104Global configuration and state information that is used by the 105resolver routines is kept in the structure 106.Va _res . 107Most of the values have reasonable defaults and can be ignored. 108Options stored in 109.Va _res.options 110are defined in 111.In resolv.h 112and are as follows. 113Options are stored as a simple bit mask containing the bitwise OR 114of the options enabled. 115.Bl -tag -width RES_USE_DNSSEC 116.It Dv RES_INIT 117True if the initial name server address and default domain name are 118initialized (i.e.\& 119.Fn res_init 120has been called). 121.It Dv RES_DEBUG 122Print debugging messages, 123if libc is compiled with 124.Dv DEBUG . 125By default on 126.Ox 127this option does nothing. 128.It Dv RES_AAONLY 129Accept authoritative answers only. 130With this option, 131.Fn res_send 132should continue until it finds an authoritative answer or finds an error. 133On 134.Ox 135this option does nothing. 136.It Dv RES_USEVC 137Use TCP connections for queries instead of UDP datagrams. 138.It Dv RES_PRIMARY 139Query the primary name server only. 140On 141.Ox 142this option does nothing. 143.It Dv RES_IGNTC 144Ignore truncation errors, i.e. don't retry with TCP. 145.It Dv RES_RECURSE 146Set the recursion-desired bit in queries. 147.Pf ( Fn res_send 148does not do iterative queries and expects the name server 149to handle recursion.) 150This option is enabled by default. 151.It Dv RES_DEFNAMES 152If set, 153.Fn res_search 154will append the default domain name to single-component names 155(those that do not contain a dot). 156This option is enabled by default. 157.It Dv RES_STAYOPEN 158Used with 159.Dv RES_USEVC 160to keep the TCP connection open between queries. 161This is useful only in programs that regularly do many queries. 162UDP should be the normal mode used. 163.It Dv RES_DNSRCH 164If this option is set, 165.Fn res_search 166will search for host names in the current domain and in parent domains; see 167.Xr hostname 7 . 168This is used by the standard host lookup routine 169.Xr gethostbyname 3 . 170This option is enabled by default. 171.It Dv RES_INSECURE_1 172Do not require the IP source address on the reply packet 173to be equal to the server's address. 174.It Dv RES_INSECURE_2 175Do not check if the query section of the reply packet 176is equal to that of the query packet. 177.It Dv RES_NOALIASES 178This option has no effect. 179In the past, it turned off the legacy 180.Ev HOSTALIASES 181feature. 182.It Dv RES_TRUSTAD 183If set, the resolver routines will set the AD flag in DNS queries and 184preserve the value of the AD flag in DNS replies. 185If not set, the resolver routines will clear the AD flag in responses. 186Direct use of this option to enable AD bit processing is discouraged. 187Instead the use of trusted name servers should be annotated with 188.Dq options trust-ad 189in 190.Xr resolv.conf 5 . 191This option is automatically enabled if 192.Xr resolv.conf 5 193only lists name servers on localhost. 194.It Dv RES_USE_INET6 195With this option 196.Xr gethostbyname 3 197will return IPv6 addresses if available. 198This option is deprecated; software should use the 199.Xr getaddrinfo 3 200interface instead of modifying the behavior of 201.Xr gethostbyname 3 . 202On some operating systems this option also causes IPv4 addresses to be 203returned as IPv4-mapped IPv6 addresses. 204For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1. 205IPv4-mapped IPv6 addresses are not supported on 206.Ox . 207.It Dv RES_USE_EDNS0 208Attach an OPT pseudo-RR for the EDNS0 extension, 209as specified in RFC 2671. 210This informs DNS servers of a client's receive buffer size, 211allowing them to take advantage of a non-default receive buffer size, 212and thus to send larger replies. 213DNS query packets with the EDNS0 extension are not compatible with 214non-EDNS0 DNS servers. 215.Ox 216uses 4096 bytes as input buffer size. 217.It Dv RES_USE_DNSSEC 218Request that the resolver uses 219Domain Name System Security Extensions (DNSSEC), 220as defined in RFCs 4033, 4034, and 4035. 221The resolver routines will use the EDNS0 extension and set the DNSSEC DO 222flag in queries, asking the name server to signal validated records by 223setting the AD flag in the reply and to attach additional DNSSEC 224records. 225The resolver routines will clear the AD flag in replies unless the name 226servers are considered trusted. 227Also, client applications are often only interested in the value of the 228AD flag, making the additional DNSSEC records a waste of network 229bandwidth. 230See the description for 231.Dq options trust-ad 232in 233.Xr resolv.conf 5 . 234.It Dv RES_USE_CD 235Set the Checking Disabled flag on queries. 236.El 237.Pp 238The 239.Fn res_init 240routine reads the configuration file (if any; see 241.Xr resolv.conf 5 ) 242to get the default domain name, search list, and the Internet address 243of the local name server(s). 244If no server is configured, the host running 245the resolver is tried. 246The current domain name is defined by the hostname 247if not specified in the configuration file; 248it can be overridden by the environment variable 249.Ev LOCALDOMAIN . 250This environment variable may contain several blank-separated 251tokens if you wish to override the search list on a per-process basis. 252This is similar to the 253.Ic search 254command in the configuration file. 255Another environment variable 256.Ev RES_OPTIONS 257can be set to override certain internal resolver options which 258are otherwise set by changing fields in the 259.Va _res 260structure or are inherited from the configuration file's 261.Ic options 262command. 263The syntax of the 264.Ev RES_OPTIONS 265environment variable is explained in 266.Xr resolv.conf 5 . 267Initialization normally occurs on the first call 268to one of the following routines. 269.Pp 270The 271.Fn res_query 272function provides an interface to the server query mechanism. 273It constructs a query, sends it to the local server, 274awaits a response, and makes preliminary checks on the reply. 275The query requests information of the specified 276.Fa type 277and 278.Fa class 279for the specified fully qualified domain name 280.Fa dname . 281The reply message is left in the 282.Fa answer 283buffer with length 284.Fa anslen 285supplied by the caller. 286Values for the 287.Fa class 288and 289.Fa type 290fields 291are defined in 292.In arpa/nameser.h . 293.Pp 294The 295.Fn res_search 296routine makes a query and awaits a response like 297.Fn res_query , 298but in addition, it implements the default and search rules controlled by the 299.Dv RES_DEFNAMES 300and 301.Dv RES_DNSRCH 302options. 303It returns the first successful reply. 304.Pp 305The remaining routines are lower-level routines used by 306.Fn res_query . 307The 308.Fn res_mkquery 309function constructs a standard query message and places it in 310.Fa buf . 311It returns the size of the query, or \-1 if the query is larger than 312.Fa buflen . 313The query type 314.Fa op 315is usually 316.Dv QUERY , 317but can be any of the query types defined in 318.In arpa/nameser.h . 319The domain name for the query is given by 320.Fa dname . 321.Fa newrr 322is currently unused but is intended for making update messages. 323.Pp 324The 325.Fn res_send 326routine sends a pre-formatted query and returns an answer. 327It will call 328.Fn res_init 329if 330.Dv RES_INIT 331is not set, send the query to the local name server, and 332handle timeouts and retries. 333The length of the reply message is returned, or \-1 if there were errors. 334.Pp 335The 336.Fn dn_comp 337function compresses the domain name 338.Fa exp_dn 339and stores it in 340.Fa comp_dn . 341The size of the compressed name is returned or \-1 if there were errors. 342The size of the array pointed to by 343.Fa comp_dn 344is given by 345.Fa length . 346The compression uses an array of pointers 347.Fa dnptrs 348to previously compressed names in the current message. 349The first pointer points 350to the beginning of the message and the list ends with 351.Dv NULL . 352The limit to the array is specified by 353.Fa lastdnptr . 354A side effect of 355.Fn dn_comp 356is to update the list of pointers for labels inserted into the message 357as the name is compressed. 358If 359.Fa dnptrs 360is 361.Dv NULL , 362names are not compressed. 363If 364.Fa lastdnptr 365is 366.Dv NULL , 367the list of labels is not updated. 368.Pp 369The 370.Fn dn_expand 371entry expands the compressed domain name 372.Fa comp_dn 373to a full domain name. 374The compressed name is contained in a query or reply message; 375.Fa msg 376is a pointer to the beginning of the message. 377The uncompressed name is placed in the buffer indicated by 378.Fa exp_dn 379which is of size 380.Fa length . 381The size of compressed name is returned or \-1 if there was an error. 382.Sh FILES 383.Bl -tag -width "/etc/resolv.confXX" 384.It Pa /etc/resolv.conf 385The configuration file. 386.El 387.Sh SEE ALSO 388.Xr gethostbyname 3 , 389.Xr resolv.conf 5 , 390.Xr hostname 7 391.Sh STANDARDS 392.Rs 393.%A M. Stahl 394.%D November 1987 395.%R RFC 1032 396.%T Domain Administrators Guide 397.Re 398.Pp 399.Rs 400.%A M. Lottor 401.%D November 1987 402.%R RFC 1033 403.%T Domain Administrators Operations Guide 404.Re 405.Pp 406.Rs 407.%A P. Mockapetris 408.%D November 1987 409.%R RFC 1034 410.%T Domain Names \(en Concepts and Facilities 411.Re 412.Pp 413.Rs 414.%A P. Mockapetris 415.%D November 1987 416.%R RFC 1035 417.%T Domain Names \(en Implementation and Specification 418.Re 419.Pp 420.Rs 421.%A J. Klensin 422.%D October 2008 423.%R RFC 5321 424.%T Simple Mail Transfer Protocol 425.Re 426.Sh HISTORY 427The functions 428.Fn res_mkquery , 429.Fn res_send , 430.Fn res_init , 431.Fn dn_comp , 432and 433.Fn dn_expand 434appeared in 435.Bx 4.3 . 436The functions 437.Fn res_query 438and 439.Fn res_search 440appeared in 441.Bx 4.3 Tahoe . 442