lib/liblwres/man/lwres.html

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