lib/libc/net/resolver.3

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  19 .\"
  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
  30 .\" SUCH DAMAGE.
  31 .\"
  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/libc/net/resolver.3,v 1.3 2006/05/26 19:39:37 swildner Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt RESOLVER 3
  38 .Os
  39 .Sh NAME
  40 .Nm res_query ,
  41 .Nm res_search ,
  42 .Nm res_mkquery ,
  43 .Nm res_send ,
  44 .Nm res_init ,
  45 .Nm dn_comp ,
  46 .Nm dn_expand
  47 .Nd resolver routines
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In netinet/in.h
  53 .In arpa/nameser.h
  54 .In resolv.h
  55 .Ft int
  56 .Fo res_query
  57 .Fa "const char *dname"
  58 .Fa "int class"
  59 .Fa "int type"
  60 .Fa "u_char *answer"
  61 .Fa "int anslen"
  62 .Fc
  63 .Ft int
  64 .Fo res_search
  65 .Fa "const char *dname"
  66 .Fa "int class"
  67 .Fa "int type"
  68 .Fa "u_char *answer"
  69 .Fa "int anslen"
  70 .Fc
  71 .Ft int
  72 .Fo res_mkquery
  73 .Fa "int op"
  74 .Fa "const char *dname"
  75 .Fa "int class"
  76 .Fa "int type"
  77 .Fa "const u_char *data"
  78 .Fa "int datalen"
  79 .Fa "const u_char *newrr_in"
  80 .Fa "u_char *buf"
  81 .Fa "int buflen"
  82 .Fc
  83 .Ft int
  84 .Fo res_send
  85 .Fa "const u_char *msg"
  86 .Fa "int msglen"
  87 .Fa "u_char *answer"
  88 .Fa "int anslen"
  89 .Fc
  90 .Ft int
  91 .Fn res_init
  92 .Fo dn_comp
  93 .Fa "const char *exp_dn"
  94 .Fa "u_char *comp_dn"
  95 .Fa "int length"
  96 .Fa "u_char **dnptrs"
  97 .Fa "u_char **lastdnptr"
  98 .Fc
  99 .Ft int
 100 .Fo dn_expand
 101 .Fa "const u_char *msg"
 102 .Fa "const u_char *eomorig"
 103 .Fa "const u_char *comp_dn"
 104 .Fa "char *exp_dn"
 105 .Fa "int length"
 106 .Fc
 107 .Sh DESCRIPTION
 108 These routines are used for making, sending and interpreting
 109 query and reply messages with Internet domain name servers.
 110 .Pp
 111 Global configuration and state information that is used by the
 112 resolver routines is kept in the structure
 113 .Em _res .
 114 Most of the values have reasonable defaults and can be ignored.
 115 Options
 116 stored in
 117 .Em _res.options
 118 are defined in
 119 .In resolv.h
 120 and are as follows.
 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
 124 .It Dv RES_INIT
 125 True if the initial name server address and default domain name are
 126 initialized (i.e.,
 127 .Fn res_init
 128 has been called).
 129 .It Dv RES_DEBUG
 130 Print debugging messages.
 131 .It Dv RES_AAONLY
 132 Accept authoritative answers only.
 133 With this option,
 134 .Fn res_send
 135 should continue until it finds an authoritative answer or finds an error.
 136 Currently this is not implemented.
 137 .It Dv RES_USEVC
 138 Use
 139 .Tn TCP
 140 connections for queries instead of
 141 .Tn UDP
 142 datagrams.
 143 .It Dv RES_STAYOPEN
 144 Used with
 145 .Dv RES_USEVC
 146 to keep the
 147 .Tn TCP
 148 connection open between
 149 queries.
 150 This is useful only in programs that regularly do many queries.
 151 .Tn UDP
 152 should be the normal mode used.
 153 .It Dv RES_IGNTC
 154 Unused currently (ignore truncation errors, i.e., don't retry with
 155 .Tn TCP ) .
 156 .It Dv RES_RECURSE
 157 Set the recursion-desired bit in queries.
 158 This is the default.
 159 .Pf ( Fn res_send
 160 does not do iterative queries and expects the name server
 161 to handle recursion.)
 162 .It Dv RES_DEFNAMES
 163 If set,
 164 .Fn res_search
 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.
 168 .It Dv RES_DNSRCH
 169 If this option is set,
 170 .Fn res_search
 171 will search for host names in the current domain and in parent domains; see
 172 .Xr hostname 7 .
 173 This is used by the standard host lookup routine
 174 .Xr gethostbyname 3 .
 175 This option is enabled by default.
 176 .It Dv RES_NOALIASES
 177 This option turns off the user level aliasing feature controlled by the
 178 .Dq Ev HOSTALIASES
 179 environment variable.  Network daemons should set this option.
 180 .It Dv RES_USE_INET6
 181 Enables support for IPv6-only applications.
 182 This causes IPv4 addresses to be returned as an IPv4 mapped address.
 183 For example,
 184 .Li 10.1.1.1
 185 will be returned as
 186 .Li ::ffff:10.1.1.1 .
 187 The option is meaningful with certain kernel configuration only.
 188 .It Dv RES_USE_EDNS0
 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.
 196 .El
 197 .Pp
 198 The
 199 .Fn res_init
 200 routine
 201 reads the configuration file (if any; see
 202 .Xr resolver 5 )
 203 to get the default domain name,
 204 search list and
 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
 211 .Ev LOCALDOMAIN .
 212 This environment variable may contain several blank-separated
 213 tokens if you wish to override the
 214 .Em "search list"
 215 on a per-process basis.  This is similar to the
 216 .Em search
 217 command in the configuration file.
 218 Another environment variable
 219 .Dq Ev RES_OPTIONS
 220 can be set to
 221 override certain internal resolver options which are otherwise
 222 set by changing fields in the
 223 .Em _res
 224 structure or are inherited from the configuration file's
 225 .Em options
 226 command.  The syntax of the
 227 .Dq Ev RES_OPTIONS
 228 environment variable is explained in
 229 .Xr resolver 5 .
 230 Initialization normally occurs on the first call
 231 to one of the following routines.
 232 .Pp
 233 The
 234 .Fn res_query
 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
 239 .Fa type
 240 and
 241 .Fa class
 242 for the specified fully-qualified domain name
 243 .Fa dname .
 244 The reply message is left in the
 245 .Fa answer
 246 buffer with length
 247 .Fa anslen
 248 supplied by the caller.
 249 .Pp
 250 The
 251 .Fn res_search
 252 routine makes a query and awaits a response like
 253 .Fn res_query ,
 254 but in addition, it implements the default and search rules
 255 controlled by the
 256 .Dv RES_DEFNAMES
 257 and
 258 .Dv RES_DNSRCH
 259 options.
 260 It returns the first successful reply.
 261 .Pp
 262 The remaining routines are lower-level routines used by
 263 .Fn res_query .
 264 The
 265 .Fn res_mkquery
 266 function
 267 constructs a standard query message and places it in
 268 .Fa buf .
 269 It returns the size of the query, or \-1 if the query is
 270 larger than
 271 .Fa buflen .
 272 The query type
 273 .Fa op
 274 is usually
 275 .Dv QUERY ,
 276 but can be any of the query types defined in
 277 .In arpa/nameser.h .
 278 The domain name for the query is given by
 279 .Fa dname .
 280 .Fa Newrr
 281 is currently unused but is intended for making update messages.
 282 .Pp
 283 The
 284 .Fn res_send
 285 routine
 286 sends a pre-formatted query and returns an answer.
 287 It will call
 288 .Fn res_init
 289 if
 290 .Dv RES_INIT
 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.
 295 .Pp
 296 The
 297 .Fn dn_comp
 298 function
 299 compresses the domain name
 300 .Fa exp_dn
 301 and stores it in
 302 .Fa comp_dn .
 303 The size of the compressed name is returned or \-1 if there were errors.
 304 The size of the array pointed to by
 305 .Fa comp_dn
 306 is given by
 307 .Fa length .
 308 The compression uses
 309 an array of pointers
 310 .Fa dnptrs
 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
 314 .Dv NULL .
 315 The limit to the array is specified by
 316 .Fa lastdnptr .
 317 A side effect of
 318 .Fn dn_comp
 319 is to update the list of pointers for
 320 labels inserted into the message
 321 as the name is compressed.
 322 If
 323 .Em dnptr
 324 is
 325 .Dv NULL ,
 326 names are not compressed.
 327 If
 328 .Fa lastdnptr
 329 is
 330 .Dv NULL ,
 331 the list of labels is not updated.
 332 .Pp
 333 The
 334 .Fn dn_expand
 335 entry
 336 expands the compressed domain name
 337 .Fa comp_dn
 338 to a full domain name
 339 The compressed name is contained in a query or reply message;
 340 .Fa msg
 341 is a pointer to the beginning of the message.
 342 The uncompressed name is placed in the buffer indicated by
 343 .Fa exp_dn
 344 which is of size
 345 .Fa length .
 346 The size of compressed name is returned or \-1 if there was an error.
 347 .Sh FILES
 348 .Bl -tag -width /etc/resolv.conf
 349 .It Pa /etc/resolv.conf
 350 The configuration file,
 351 see
 352 .Xr resolver 5 .
 353 .El
 354 .Sh SEE ALSO
 355 .Xr gethostbyname 3 ,
 356 .Xr resolver 5 ,
 357 .Xr hostname 7 ,
 358 .Xr named 8
 359 .Pp
 360 .%T RFC1032 ,
 361 .%T RFC1033 ,
 362 .%T RFC1034 ,
 363 .%T RFC1035 ,
 364 .%T RFC974
 365 .Rs
 366 .%T "Name Server Operations Guide for BIND"
 367 .Re
 368 .Sh HISTORY
 369 The
 370 .Nm
 371 function appeared in
 372 .Bx 4.3 .