1.\" $OpenBSD: res_init.3,v 1.4 2020/04/25 21:06:17 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: April 25 2020 $ 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_USE_INET6 183With this option 184.Xr gethostbyname 3 185will return IPv6 addresses if available. 186This option is deprecated; software should use the 187.Xr getaddrinfo 3 188interface instead of modifying the behavior of 189.Xr gethostbyname 3 . 190On some operating systems this option also causes IPv4 addresses to be 191returned as IPv4-mapped IPv6 addresses. 192For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1. 193IPv4-mapped IPv6 addresses are not supported on 194.Ox . 195.It Dv RES_USE_EDNS0 196Attach an OPT pseudo-RR for the EDNS0 extension, 197as specified in RFC 2671. 198This informs DNS servers of a client's receive buffer size, 199allowing them to take advantage of a non-default receive buffer size, 200and thus to send larger replies. 201DNS query packets with the EDNS0 extension are not compatible with 202non-EDNS0 DNS servers. 203.Ox 204uses 4096 bytes as input buffer size. 205.It Dv RES_USE_DNSSEC 206Request that the resolver uses 207Domain Name System Security Extensions (DNSSEC), 208as defined in RFCs 4033, 4034, and 4035. 209.It Dv RES_USE_CD 210Set the Checking Disabled flag on queries. 211.El 212.Pp 213The 214.Fn res_init 215routine reads the configuration file (if any; see 216.Xr resolv.conf 5 ) 217to get the default domain name, search list, and the Internet address 218of the local name server(s). 219If no server is configured, the host running 220the resolver is tried. 221The current domain name is defined by the hostname 222if not specified in the configuration file; 223it can be overridden by the environment variable 224.Ev LOCALDOMAIN . 225This environment variable may contain several blank-separated 226tokens if you wish to override the search list on a per-process basis. 227This is similar to the 228.Ic search 229command in the configuration file. 230Another environment variable 231.Ev RES_OPTIONS 232can be set to override certain internal resolver options which 233are otherwise set by changing fields in the 234.Va _res 235structure or are inherited from the configuration file's 236.Ic options 237command. 238The syntax of the 239.Ev RES_OPTIONS 240environment variable is explained in 241.Xr resolv.conf 5 . 242Initialization normally occurs on the first call 243to one of the following routines. 244.Pp 245The 246.Fn res_query 247function provides an interface to the server query mechanism. 248It constructs a query, sends it to the local server, 249awaits a response, and makes preliminary checks on the reply. 250The query requests information of the specified 251.Fa type 252and 253.Fa class 254for the specified fully qualified domain name 255.Fa dname . 256The reply message is left in the 257.Fa answer 258buffer with length 259.Fa anslen 260supplied by the caller. 261Values for the 262.Fa class 263and 264.Fa type 265fields 266are defined in 267.In arpa/nameser.h . 268.Pp 269The 270.Fn res_search 271routine makes a query and awaits a response like 272.Fn res_query , 273but in addition, it implements the default and search rules controlled by the 274.Dv RES_DEFNAMES 275and 276.Dv RES_DNSRCH 277options. 278It returns the first successful reply. 279.Pp 280The remaining routines are lower-level routines used by 281.Fn res_query . 282The 283.Fn res_mkquery 284function constructs a standard query message and places it in 285.Fa buf . 286It returns the size of the query, or \-1 if the query is larger than 287.Fa buflen . 288The query type 289.Fa op 290is usually 291.Dv QUERY , 292but can be any of the query types defined in 293.In arpa/nameser.h . 294The domain name for the query is given by 295.Fa dname . 296.Fa newrr 297is currently unused but is intended for making update messages. 298.Pp 299The 300.Fn res_send 301routine sends a pre-formatted query and returns an answer. 302It will call 303.Fn res_init 304if 305.Dv RES_INIT 306is not set, send the query to the local name server, and 307handle timeouts and retries. 308The length of the reply message is returned, or \-1 if there were errors. 309.Pp 310The 311.Fn dn_comp 312function compresses the domain name 313.Fa exp_dn 314and stores it in 315.Fa comp_dn . 316The size of the compressed name is returned or \-1 if there were errors. 317The size of the array pointed to by 318.Fa comp_dn 319is given by 320.Fa length . 321The compression uses an array of pointers 322.Fa dnptrs 323to previously compressed names in the current message. 324The first pointer points 325to the beginning of the message and the list ends with 326.Dv NULL . 327The limit to the array is specified by 328.Fa lastdnptr . 329A side effect of 330.Fn dn_comp 331is to update the list of pointers for labels inserted into the message 332as the name is compressed. 333If 334.Fa dnptrs 335is 336.Dv NULL , 337names are not compressed. 338If 339.Fa lastdnptr 340is 341.Dv NULL , 342the list of labels is not updated. 343.Pp 344The 345.Fn dn_expand 346entry expands the compressed domain name 347.Fa comp_dn 348to a full domain name. 349The compressed name is contained in a query or reply message; 350.Fa msg 351is a pointer to the beginning of the message. 352The uncompressed name is placed in the buffer indicated by 353.Fa exp_dn 354which is of size 355.Fa length . 356The size of compressed name is returned or \-1 if there was an error. 357.Sh FILES 358.Bl -tag -width "/etc/resolv.confXX" 359.It Pa /etc/resolv.conf 360The configuration file. 361.El 362.Sh SEE ALSO 363.Xr gethostbyname 3 , 364.Xr resolv.conf 5 , 365.Xr hostname 7 366.Sh STANDARDS 367.Rs 368.%A M. Stahl 369.%D November 1987 370.%R RFC 1032 371.%T Domain Administrators Guide 372.Re 373.Pp 374.Rs 375.%A M. Lottor 376.%D November 1987 377.%R RFC 1033 378.%T Domain Administrators Operations Guide 379.Re 380.Pp 381.Rs 382.%A P. Mockapetris 383.%D November 1987 384.%R RFC 1034 385.%T Domain Names \(en Concepts and Facilities 386.Re 387.Pp 388.Rs 389.%A P. Mockapetris 390.%D November 1987 391.%R RFC 1035 392.%T Domain Names \(en Implementation and Specification 393.Re 394.Pp 395.Rs 396.%A J. Klensin 397.%D October 2008 398.%R RFC 5321 399.%T Simple Mail Transfer Protocol 400.Re 401.Sh HISTORY 402The functions 403.Fn res_mkquery , 404.Fn res_send , 405.Fn res_init , 406.Fn dn_comp , 407and 408.Fn dn_expand 409appeared in 410.Bx 4.3 . 411The functions 412.Fn res_query 413and 414.Fn res_search 415appeared in 416.Bx 4.3 Tahoe . 417