contrib/bind-9.2.4rc7/lib/lwres/man/lwres.html

   1 <!--
   2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2001  Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17
  18 <!-- $Id: lwres.html,v 1.4.2.2 2004/03/15 04:45:00 marka Exp $ -->
  19
  20 <HTML
  21 ><HEAD
  22 ><TITLE
  23 >lwres</TITLE
  24 ><META
  25 NAME="GENERATOR"
  26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
  27 "></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 BGCOLOR="#FFFFFF"
  31 TEXT="#000000"
  32 LINK="#0000FF"
  33 VLINK="#840084"
  34 ALINK="#0000FF"
  35 ><H1
  36 ><A
  37 NAME="AEN1"
  38 >lwres</A
  39 ></H1
  40 ><DIV
  41 CLASS="REFNAMEDIV"
  42 ><A
  43 NAME="AEN8"
  44 ></A
  45 ><H2
  46 >Name</H2
  47 >lwres&nbsp;--&nbsp;introduction to the lightweight resolver library</DIV
  48 ><DIV
  49 CLASS="REFSYNOPSISDIV"
  50 ><A
  51 NAME="AEN11"
  52 ></A
  53 ><H2
  54 >Synopsis</H2
  55 ><DIV
  56 CLASS="FUNCSYNOPSIS"
  57 ><A
  58 NAME="AEN12"
  59 ></A
  60 ><P
  61 ></P
  62 ><PRE
  63 CLASS="FUNCSYNOPSISINFO"
  64 >#include &lt;lwres/lwres.h&gt;</PRE
  65 ><P
  66 ></P
  67 ></DIV
  68 ></DIV
  69 ><DIV
  70 CLASS="REFSECT1"
  71 ><A
  72 NAME="AEN14"
  73 ></A
  74 ><H2
  75 >DESCRIPTION</H2
  76 ><P
  77 >The BIND 9 lightweight resolver library is a simple, name service
  78 independent stub resolver library.  It provides hostname-to-address
  79 and address-to-hostname lookup services to applications by
  80 transmitting lookup requests to a resolver daemon
  81 <B
  82 CLASS="COMMAND"
  83 >lwresd</B
  84 >
  85 running on the local host. The resover daemon performs the
  86 lookup using the DNS or possibly other name service protocols,
  87 and returns the results to the application through the library.
  88 The library and resolver daemon communicate using a simple
  89 UDP-based protocol.</P
  90 ></DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="AEN18"
  95 ></A
  96 ><H2
  97 >OVERVIEW</H2
  98 ><P
  99 >The lwresd library implements multiple name service APIs.
 100 The standard
 101 <TT
 102 CLASS="FUNCTION"
 103 >gethostbyname()</TT
 104 >,
 105 <TT
 106 CLASS="FUNCTION"
 107 >gethostbyaddr()</TT
 108 >,
 109 <TT
 110 CLASS="FUNCTION"
 111 >gethostbyname_r()</TT
 112 >,
 113 <TT
 114 CLASS="FUNCTION"
 115 >gethostbyaddr_r()</TT
 116 >,
 117 <TT
 118 CLASS="FUNCTION"
 119 >getaddrinfo()</TT
 120 >,
 121 <TT
 122 CLASS="FUNCTION"
 123 >getipnodebyname()</TT
 124 >,
 125 and
 126 <TT
 127 CLASS="FUNCTION"
 128 >getipnodebyaddr()</TT
 129 >
 130 functions are all supported.  To allow the lwres library to coexist
 131 with system libraries that define functions of the same name,
 132 the library defines these functions with names prefixed by
 133 <TT
 134 CLASS="LITERAL"
 135 >lwres_</TT
 136 >.
 137 To define the standard names, applications must include the
 138 header file
 139 <TT
 140 CLASS="FILENAME"
 141 >&lt;lwres/netdb.h&gt;</TT
 142 >
 143 which contains macro definitions mapping the standard function names
 144 into
 145 <TT
 146 CLASS="LITERAL"
 147 >lwres_</TT
 148 >
 149 prefixed ones.  Operating system vendors who integrate the lwres
 150 library into their base distributions should rename the functions
 151 in the library proper so that the renaming macros are not needed.</P
 152 ><P
 153 >The library also provides a native API consisting of the functions
 154 <TT
 155 CLASS="FUNCTION"
 156 >lwres_getaddrsbyname()</TT
 157 >
 158 and
 159 <TT
 160 CLASS="FUNCTION"
 161 >lwres_getnamebyaddr()</TT
 162 >.
 163 These may be called by applications that require more detailed
 164 control over the lookup process than the standard functions
 165 provide.</P
 166 ><P
 167 >In addition to these name service independent address lookup
 168 functions, the library implements a new, experimental API
 169 for looking up arbitrary DNS resource records, using the
 170 <TT
 171 CLASS="FUNCTION"
 172 >lwres_getaddrsbyname()</TT
 173 >
 174 function.</P
 175 ><P
 176 >Finally, there is a low-level API for converting lookup
 177 requests and responses to and from raw lwres protocol packets.
 178 This API can be used by clients requiring nonblocking operation,
 179 and is also used when implementing the server side of the lwres
 180 protocol, for example in the
 181 <B
 182 CLASS="COMMAND"
 183 >lwresd</B
 184 >
 185 resolver daemon.  The use of this low-level API in clients
 186 and servers is outlined in the following sections.</P
 187 ></DIV
 188 ><DIV
 189 CLASS="REFSECT1"
 190 ><A
 191 NAME="AEN38"
 192 ></A
 193 ><H2
 194 >CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
 195 ><P
 196 >When a client program wishes to make an lwres request using the
 197 native low-level API, it typically performs the following
 198 sequence of actions.</P
 199 ><P
 200 >(1) Allocate or use an existing <SPAN
 201 CLASS="TYPE"
 202 >lwres_packet_t</SPAN
 203 >,
 204 called <TT
 205 CLASS="VARNAME"
 206 >pkt</TT
 207 > below.</P
 208 ><P
 209 >(2) Set <TT
 210 CLASS="STRUCTFIELD"
 211 ><I
 212 >pkt.recvlength</I
 213 ></TT
 214 > to the maximum length we will accept.
 215 This is done so the receiver of our packets knows how large our receive
 216 buffer is.  The "default" is a constant in
 217 <TT
 218 CLASS="FILENAME"
 219 >lwres.h</TT
 220 >: <TT
 221 CLASS="CONSTANT"
 222 >LWRES_RECVLENGTH = 4096</TT
 223 >.</P
 224 ><P
 225 >(3) Set <TT
 226 CLASS="STRUCTFIELD"
 227 ><I
 228 >pkt.serial</I
 229 ></TT
 230 >
 231 to a unique serial number.  This value is echoed
 232 back to the application by the remote server.</P
 233 ><P
 234 >(4) Set <TT
 235 CLASS="STRUCTFIELD"
 236 ><I
 237 >pkt.pktflags</I
 238 ></TT
 239 >.  Usually this is set to 0.</P
 240 ><P
 241 >(5) Set <TT
 242 CLASS="STRUCTFIELD"
 243 ><I
 244 >pkt.result</I
 245 ></TT
 246 > to 0.</P
 247 ><P
 248 >(6) Call <TT
 249 CLASS="FUNCTION"
 250 >lwres_*request_render()</TT
 251 >,
 252 or marshall in the data using the primitives
 253 such as <TT
 254 CLASS="FUNCTION"
 255 >lwres_packet_render()</TT
 256 >
 257 and storing the packet data.</P
 258 ><P
 259 >(7) Transmit the resulting buffer.</P
 260 ><P
 261 >(8) Call <TT
 262 CLASS="FUNCTION"
 263 >lwres_*response_parse()</TT
 264 >
 265 to parse any packets received.</P
 266 ><P
 267 >(9) Verify that the opcode and serial match a request, and process the
 268 packet specific information contained in the body.</P
 269 ></DIV
 270 ><DIV
 271 CLASS="REFSECT1"
 272 ><A
 273 NAME="AEN61"
 274 ></A
 275 ><H2
 276 >SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
 277 ><P
 278 >When implementing the server side of the lightweight resolver
 279 protocol using the lwres library, a sequence of actions like the
 280 following is typically involved in processing each request packet.</P
 281 ><P
 282 >Note that the same <SPAN
 283 CLASS="TYPE"
 284 >lwres_packet_t</SPAN
 285 > is used
 286 in both the <TT
 287 CLASS="FUNCTION"
 288 >_parse()</TT
 289 > and <TT
 290 CLASS="FUNCTION"
 291 >_render()</TT
 292 > calls,
 293 with only a few modifications made
 294 to the packet header's contents between uses.  This method is recommended
 295 as it keeps the serial, opcode, and other fields correct.</P
 296 ><P
 297 >(1) When a packet is received, call <TT
 298 CLASS="FUNCTION"
 299 >lwres_*request_parse()</TT
 300 > to
 301 unmarshall it.  This returns a <SPAN
 302 CLASS="TYPE"
 303 >lwres_packet_t</SPAN
 304 > (also called <TT
 305 CLASS="VARNAME"
 306 >pkt</TT
 307 >, below)
 308 as well as a data specific type, such as <SPAN
 309 CLASS="TYPE"
 310 >lwres_gabnrequest_t</SPAN
 311 >.</P
 312 ><P
 313 >(2) Process the request in the data specific type.</P
 314 ><P
 315 >(3) Set the <TT
 316 CLASS="STRUCTFIELD"
 317 ><I
 318 >pkt.result</I
 319 ></TT
 320 >,
 321 <TT
 322 CLASS="STRUCTFIELD"
 323 ><I
 324 >pkt.recvlength</I
 325 ></TT
 326 > as above.  All other fields can
 327 be left untouched since they were filled in by the <TT
 328 CLASS="FUNCTION"
 329 >*_parse()</TT
 330 > call
 331 above.  If using <TT
 332 CLASS="FUNCTION"
 333 >lwres_*response_render()</TT
 334 >,
 335 <TT
 336 CLASS="STRUCTFIELD"
 337 ><I
 338 >pkt.pktflags</I
 339 ></TT
 340 > will be set up
 341 properly.  Otherwise, the <TT
 342 CLASS="CONSTANT"
 343 >LWRES_LWPACKETFLAG_RESPONSE</TT
 344 > bit should be
 345 set.</P
 346 ><P
 347 >(4) Call the data specific rendering function, such as
 348 <TT
 349 CLASS="FUNCTION"
 350 >lwres_gabnresponse_render()</TT
 351 >.</P
 352 ><P
 353 >(5) Send the resulting packet to the client.</P
 354 ><P
 355 ></P
 356 ></DIV
 357 ><DIV
 358 CLASS="REFSECT1"
 359 ><A
 360 NAME="AEN85"
 361 ></A
 362 ><H2
 363 >SEE ALSO</H2
 364 ><P
 365 ><SPAN
 366 CLASS="CITEREFENTRY"
 367 ><SPAN
 368 CLASS="REFENTRYTITLE"
 369 >lwres_gethostent</SPAN
 370 >(3)</SPAN
 371 >,
 372
 373 <SPAN
 374 CLASS="CITEREFENTRY"
 375 ><SPAN
 376 CLASS="REFENTRYTITLE"
 377 >lwres_getipnode</SPAN
 378 >(3)</SPAN
 379 >,
 380
 381 <SPAN
 382 CLASS="CITEREFENTRY"
 383 ><SPAN
 384 CLASS="REFENTRYTITLE"
 385 >lwres_getnameinfo</SPAN
 386 >(3)</SPAN
 387 >,
 388
 389 <SPAN
 390 CLASS="CITEREFENTRY"
 391 ><SPAN
 392 CLASS="REFENTRYTITLE"
 393 >lwres_noop</SPAN
 394 >(3)</SPAN
 395 >,
 396
 397 <SPAN
 398 CLASS="CITEREFENTRY"
 399 ><SPAN
 400 CLASS="REFENTRYTITLE"
 401 >lwres_gabn</SPAN
 402 >(3)</SPAN
 403 >,
 404
 405 <SPAN
 406 CLASS="CITEREFENTRY"
 407 ><SPAN
 408 CLASS="REFENTRYTITLE"
 409 >lwres_gnba</SPAN
 410 >(3)</SPAN
 411 >,
 412
 413 <SPAN
 414 CLASS="CITEREFENTRY"
 415 ><SPAN
 416 CLASS="REFENTRYTITLE"
 417 >lwres_context</SPAN
 418 >(3)</SPAN
 419 >,
 420
 421 <SPAN
 422 CLASS="CITEREFENTRY"
 423 ><SPAN
 424 CLASS="REFENTRYTITLE"
 425 >lwres_config</SPAN
 426 >(3)</SPAN
 427 >,
 428
 429 <SPAN
 430 CLASS="CITEREFENTRY"
 431 ><SPAN
 432 CLASS="REFENTRYTITLE"
 433 >resolver</SPAN
 434 >(5)</SPAN
 435 >,
 436
 437 <SPAN
 438 CLASS="CITEREFENTRY"
 439 ><SPAN
 440 CLASS="REFENTRYTITLE"
 441 >lwresd</SPAN
 442 >(8)</SPAN
 443 >.&#13;</P
 444 ></DIV
 445 ></BODY
 446 ></HTML
 447 >