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