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