original/man3/resolver.3

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