1 .\" Copyright (c) 1985, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)resolver.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/net/resolver.3,v 1.11.2.7 2001/12/14 18:33:55 ru Exp $
34 .\" $DragonFly: src/lib/libcr/net/Attic/resolver.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
57 .Fa "const char *dname"
65 .Fa "const char *dname"
74 .Fa "const char *dname"
77 .Fa "const u_char *data"
79 .Fa "const u_char *newrr_in"
85 .Fa "const u_char *msg"
93 .Fa "const char *exp_dn"
97 .Fa "u_char **lastdnptr"
101 .Fa "const u_char *msg"
102 .Fa "const u_char *eomorig"
103 .Fa "const u_char *comp_dn"
108 These routines are used for making, sending and interpreting
109 query and reply messages with Internet domain name servers.
111 Global configuration and state information that is used by the
112 resolver routines is kept in the structure
114 Most of the values have reasonable defaults and can be ignored.
121 Options are stored as a simple bit mask containing the bitwise ``or''
122 of the options enabled.
123 .Bl -tag -width RES_USE_INET6
125 True if the initial name server address and default domain name are
130 Print debugging messages.
132 Accept authoritative answers only.
135 should continue until it finds an authoritative answer or finds an error.
136 Currently this is not implemented.
140 connections for queries instead of
148 connection open between
150 This is useful only in programs that regularly do many queries.
152 should be the normal mode used.
154 Unused currently (ignore truncation errors, i.e., don't retry with
157 Set the recursion-desired bit in queries.
160 does not do iterative queries and expects the name server
161 to handle recursion.)
165 will append the default domain name to single-component names
166 (those that do not contain a dot).
167 This option is enabled by default.
169 If this option is set,
171 will search for host names in the current domain and in parent domains; see
173 This is used by the standard host lookup routine
174 .Xr gethostbyname 3 .
175 This option is enabled by default.
177 This option turns off the user level aliasing feature controlled by the
179 environment variable. Network daemons should set this option.
181 Enables support for IPv6-only applications.
182 This causes IPv4 addresses to be returned as an IPv4 mapped address.
186 .Li ::ffff:10.1.1.1 .
187 The option is meaningful with certain kernel configuration only.
189 Enables support for OPT pseudo-RR for EDNS0 extension.
190 With the option, resolver code will attach OPT pseudo-RR into DNS queries,
191 to inform of our receive buffer size.
192 The option will allow DNS servers to take advantage of non-default receive
193 buffer size, and to send larger replies.
194 DNS query packets with EDNS0 extension is not compatible with
195 non-EDNS0 DNS servers.
201 reads the configuration file (if any; see
203 to get the default domain name,
205 the Internet address of the local name server(s).
206 If no server is configured, the host running
207 the resolver is tried.
208 The current domain name is defined by the hostname
209 if not specified in the configuration file;
210 it can be overridden by the environment variable
212 This environment variable may contain several blank-separated
213 tokens if you wish to override the
215 on a per-process basis. This is similar to the
217 command in the configuration file.
218 Another environment variable
221 override certain internal resolver options which are otherwise
222 set by changing fields in the
224 structure or are inherited from the configuration file's
226 command. The syntax of the
228 environment variable is explained in
230 Initialization normally occurs on the first call
231 to one of the following routines.
235 function provides an interface to the server query mechanism.
236 It constructs a query, sends it to the local server,
237 awaits a response, and makes preliminary checks on the reply.
238 The query requests information of the specified
242 for the specified fully-qualified domain name
244 The reply message is left in the
248 supplied by the caller.
252 routine makes a query and awaits a response like
254 but in addition, it implements the default and search rules
260 It returns the first successful reply.
262 The remaining routines are lower-level routines used by
267 constructs a standard query message and places it in
269 It returns the size of the query, or \-1 if the query is
276 but can be any of the query types defined in
277 .Aq Pa arpa/nameser.h .
278 The domain name for the query is given by
281 is currently unused but is intended for making update messages.
286 sends a pre-formatted query and returns an answer.
291 is not set, send the query to the local name server, and
292 handle timeouts and retries.
293 The length of the reply message is returned, or
294 \-1 if there were errors.
299 compresses the domain name
303 The size of the compressed name is returned or \-1 if there were errors.
304 The size of the array pointed to by
311 to previously-compressed names in the current message.
312 The first pointer points to
313 the beginning of the message and the list ends with
315 The limit to the array is specified by
319 is to update the list of pointers for
320 labels inserted into the message
321 as the name is compressed.
326 names are not compressed.
331 the list of labels is not updated.
336 expands the compressed domain name
338 to a full domain name
339 The compressed name is contained in a query or reply message;
341 is a pointer to the beginning of the message.
342 The uncompressed name is placed in the buffer indicated by
346 The size of compressed name is returned or \-1 if there was an error.
348 .Bl -tag -width /etc/resolv.conf
349 .It Pa /etc/resolv.conf
350 The configuration file,
355 .Xr gethostbyname 3 ,
366 .%T "Name Server Operations Guide for BIND"