original/man3/resolver.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified 2004-10-31 by aeb
  31 .\"
  32 .TH RESOLVER 3 2014-05-28 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 res_init, res_query, res_search, res_querydomain, res_mkquery, res_send,
  35 dn_comp, dn_expand \- resolver routines
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <netinet/in.h>
  39 .B #include <arpa/nameser.h>
  40 .B #include <resolv.h>
  41 .B extern struct __res_state _res;
  42 .sp
  43 .B int res_init(void);
  44 .sp
  45 .BI "int res_query(const char *" dname ", int " class ", int " type ,
  46 .RS
  47 .BI "unsigned char *" answer ", int " anslen );
  48 .RE
  49 .sp
  50 .BI "int res_search(const char *" dname ", int " class ", int " type ,
  51 .RS
  52 .BI "unsigned char *" answer ", int " anslen );
  53 .RE
  54 .sp
  55 .BI "int res_querydomain(const char *" name ", const char *" domain ,
  56 .RS
  57 .BI "int " class ", int " type ", unsigned char *" answer ,
  58 .BI "int " anslen );
  59 .RE
  60 .sp
  61 .BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
  62 .RS
  63 .BI "int " type ", const unsigned char *" data ", int " datalen ,
  64 .BI "const unsigned char *" newrr ", unsigned char *" buf ", int " buflen );
  65 .RE
  66 .sp
  67 .BI "int res_send(const unsigned char *" msg ", int " msglen ,
  68 .RS
  69 .BI "unsigned char *" answer ", int " anslen );
  70 .RE
  71 .sp
  72 .BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn ,
  73 .RS
  74 .BI "int " length ", unsigned char **" dnptrs ", unsigned char **" lastdnptr );
  75 .RE
  76 .sp
  77 .BI "int dn_expand(const unsigned char *" msg ", const unsigned char *" eomorig ,
  78 .RS
  79 .BI "const unsigned char *" comp_dn ", char *" exp_dn ,
  80 .BI "int " length );
  81 .RE
  82 .fi
  83 .sp
  84 Link with \fI\-lresolv\fP.
  85 .SH DESCRIPTION
  86 These functions make queries to and interpret the responses from Internet
  87 domain name servers.
  88 .PP
  89 The
  90 .BR res_init ()
  91 function reads the configuration files (see
  92 .BR resolv.conf (5))
  93 to get the default domain name, search order and name
  94 server address(es).
  95 If no server is given, the local host is tried.
  96 If no domain is given, that associated with the local host is used.
  97 It can be overridden with the environment variable
  98 .BR LOCALDOMAIN .
  99 .BR res_init ()
 100 is normally executed by the first call to one of the
 101 other functions.
 102 .PP
 103 The
 104 .BR res_query ()
 105 function queries the name server for the
 106 fully qualified domain name \fIname\fP of specified \fItype\fP and
 107 \fIclass\fP.
 108 The reply is left in the buffer \fIanswer\fP of length
 109 \fIanslen\fP supplied by the caller.
 110 .PP
 111 The
 112 .BR res_search ()
 113 function makes a query and waits for the response
 114 like
 115 .BR res_query (),
 116 but in addition implements the default and search
 117 rules controlled by
 118 .B RES_DEFNAMES
 119 and
 120 .B RES_DNSRCH
 121 (see description of
 122 \fI_res\fP options below).
 123 .PP
 124 The
 125 .BR res_querydomain ()
 126 function makes a query using
 127 .BR res_query ()
 128 on the concatenation of \fIname\fP and \fIdomain\fP.
 129 .PP
 130 The following functions are lower-level routines used by
 131 .BR res_query ().
 132 .PP
 133 The
 134 .BR res_mkquery ()
 135 function constructs a query message in \fIbuf\fP
 136 of length \fIbuflen\fP for the domain name \fIdname\fP.
 137 The query type
 138 \fIop\fP is usually
 139 .BR QUERY ,
 140 but can be any of the types defined in
 141 \fI<arpa/nameser.h>\fP.
 142 \fInewrr\fP is currently unused.
 143 .PP
 144 The
 145 .BR res_send ()
 146 function sends a preformatted query given in
 147 \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP
 148 which is of length \fIanslen\fP.
 149 It will call
 150 .BR res_init (),
 151 if it
 152 has not already been called.
 153 .PP
 154 The
 155 .BR dn_comp ()
 156 function compresses the domain name \fIexp_dn\fP
 157 and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP.
 158 The compression uses an array of pointers \fIdnptrs\fP to previously
 159 compressed names in the current message.
 160 The first pointer points
 161 to the beginning of the message and the list ends with NULL.
 162 The limit of the array is specified by \fIlastdnptr\fP.
 163 If \fIdnptr\fP is NULL, domain names are not compressed.
 164 If \fIlastdnptr\fP is NULL, the list
 165 of labels is not updated.
 166 .PP
 167 The
 168 .BR dn_expand ()
 169 function expands the compressed domain name
 170 \fIcomp_dn\fP to a full domain name, which is placed in the buffer
 171 \fIexp_dn\fP of size \fIlength\fP.
 172 The compressed name is contained
 173 in a query or reply message, and \fImsg\fP points to the beginning of
 174 the message.
 175 .PP
 176 The resolver routines use global configuration and state information
 177 contained in the structure \fI_res\fP, which is defined in
 178 \fI<resolv.h>\fP.
 179 The only field that is normally manipulated by the
 180 user is \fI_res.options\fP.
 181 This field can contain the bitwise "OR"
 182 of the following options:
 183 .TP
 184 .B RES_INIT
 185 True if
 186 .BR res_init ()
 187 has been called.
 188 .TP
 189 .B RES_DEBUG
 190 Print debugging messages.
 191 This option is available only if glibc was built with debugging enabled,
 192 .\" See resolv/README.
 193 .\" Support for RES_DEBUG was made conditional in glibc 2.2.
 194 which is not the default.
 195 .TP
 196 .B RES_AAONLY
 197 Accept authoritative answers only.
 198 .BR res_send ()
 199 continues until
 200 it finds an authoritative answer or returns an error.  [Not currently
 201 implemented].
 202 .TP
 203 .B RES_USEVC
 204 Use TCP connections for queries rather than UDP datagrams.
 205 .TP
 206 .B RES_PRIMARY
 207 Query primary domain name server only.
 208 .TP
 209 .B RES_IGNTC
 210 Ignore truncation errors.
 211 Don't retry with TCP.  [Not currently
 212 implemented].
 213 .TP
 214 .B RES_RECURSE
 215 Set the recursion desired bit in queries.
 216 Recursion is carried out
 217 by the domain name server, not by
 218 .BR res_send ().
 219 [Enabled by default].
 220 .TP
 221 .B RES_DEFNAMES
 222 If set,
 223 .BR res_search ()
 224 will append the default domain name to
 225 single component names\(emthat is, those that do not contain a dot.
 226 [Enabled by default].
 227 .TP
 228 .B RES_STAYOPEN
 229 Used with
 230 .B RES_USEVC
 231 to keep the TCP connection open between queries.
 232 .TP
 233 .B RES_DNSRCH
 234 If set,
 235 .BR res_search ()
 236 will search for hostnames in the current
 237 domain and in parent domains.
 238 This option is used by
 239 .BR gethostbyname (3).
 240 [Enabled by default].
 241 .PP
 242 This list is not complete.
 243 You can find some other flags described in
 244 .BR resolv.conf (5).
 245 .SH RETURN VALUE
 246 The
 247 .BR res_init ()
 248 function returns 0 on success, or \-1 if an error
 249 occurs.
 250 .PP
 251 The
 252 .BR res_query (),
 253 .BR res_search (),
 254 .BR res_querydomain (),
 255 .BR res_mkquery ()
 256 and
 257 .BR res_send ()
 258 functions return the length
 259 of the response, or \-1 if an error occurs.
 260 .PP
 261 The
 262 .BR dn_comp ()
 263 and
 264 .BR dn_expand ()
 265 functions return the length
 266 of the compressed name, or \-1 if an error occurs.
 267 .SH FILES
 268 .nf
 269 /etc/resolv.conf          resolver configuration file
 270 /etc/host.conf            resolver configuration file
 271 .fi
 272 .SH CONFORMING TO
 273 4.3BSD.
 274 .SH SEE ALSO
 275 .BR gethostbyname (3),
 276 .BR resolv.conf (5),
 277 .BR resolver (5),
 278 .BR hostname (7),
 279 .BR named (8)
 280 .SH COLOPHON
 281 This page is part of release 3.79 of the Linux
 282 .I man-pages
 283 project.
 284 A description of the project,
 285 information about reporting bugs,
 286 and the latest version of this page,
 287 can be found at
 288 \%http://www.kernel.org/doc/man\-pages/.