lwres.html revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - Copyright (C) 2000, 2001 Internet Software Consortium.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - Permission to use, copy, modify, and distribute this software for any
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - purpose with or without fee is hereby granted, provided that the above
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - copyright notice and this permission notice appear in all copies.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt<!-- $Id: lwres.html,v 1.10 2005/04/07 03:50:00 marka Exp $ -->
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres</TITLE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntNAME="GENERATOR"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFENTRY"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntBGCOLOR="#FFFFFF"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntTEXT="#000000"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntLINK="#0000FF"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntVLINK="#840084"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntALINK="#0000FF"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFNAMEDIV"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres -- introduction to the lightweight resolver library</DIV
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFSYNOPSISDIV"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>Synopsis</H2
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCSYNOPSIS"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCSYNOPSISINFO"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFSECT1"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>DESCRIPTION</H2
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>The BIND 9 lightweight resolver library is a simple, name service
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntindependent stub resolver library. It provides hostname-to-address
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntand address-to-hostname lookup services to applications by
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunttransmitting lookup requests to a resolver daemon
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="COMMAND"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntrunning on the local host. The resover daemon performs the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntlookup using the DNS or possibly other name service protocols,
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntand returns the results to the application through the library.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntThe library and resolver daemon communicate using a simple
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntUDP-based protocol.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFSECT1"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>OVERVIEW</H2
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>The lwresd library implements multiple name service APIs.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>gethostbyname()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>gethostbyaddr()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>gethostbyname_r()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>gethostbyaddr_r()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>getaddrinfo()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>getipnodebyname()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>getipnodebyaddr()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntfunctions are all supported. To allow the lwres library to coexist
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntwith system libraries that define functions of the same name,
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntthe library defines these functions with names prefixed by
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="LITERAL"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntTo define the standard names, applications must include the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FILENAME"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntwhich contains macro definitions mapping the standard function names
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="LITERAL"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntprefixed ones. Operating system vendors who integrate the lwres
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntlibrary into their base distributions should rename the functions
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntin the library proper so that the renaming macros are not needed.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>The library also provides a native API consisting of the functions
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_getaddrsbyname()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_getnamebyaddr()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntThese may be called by applications that require more detailed
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntcontrol over the lookup process than the standard functions
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>In addition to these name service independent address lookup
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntfunctions, the library implements a new, experimental API
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntfor looking up arbitrary DNS resource records, using the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_getaddrsbyname()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>Finally, there is a low-level API for converting lookup
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntrequests and responses to and from raw lwres protocol packets.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntThis API can be used by clients requiring nonblocking operation,
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntand is also used when implementing the server side of the lwres
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntprotocol, for example in the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="COMMAND"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntresolver daemon. The use of this low-level API in clients
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntand servers is outlined in the following sections.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFSECT1"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>When a client program wishes to make an lwres request using the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntnative low-level API, it typically performs the following
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntsequence of actions.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(1) Allocate or use an existing <SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_packet_t</SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="VARNAME"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(2) Set <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt> to the maximum length we will accept.
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntThis is done so the receiver of our packets knows how large our receive
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntbuffer is. The "default" is a constant in
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FILENAME"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="CONSTANT"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>LWRES_RECVLENGTH = 4096</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(3) Set <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntto a unique serial number. This value is echoed
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntback to the application by the remote server.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(4) Set <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>. Usually this is set to 0.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(5) Set <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(6) Call <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_*request_render()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntor marshall in the data using the primitives
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntsuch as <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_packet_render()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntand storing the packet data.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(7) Transmit the resulting buffer.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(8) Call <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_*response_parse()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntto parse any packets received.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(9) Verify that the opcode and serial match a request, and process the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntpacket specific information contained in the body.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="REFSECT1"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>When implementing the server side of the lightweight resolver
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntprotocol using the lwres library, a sequence of actions like the
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntfollowing is typically involved in processing each request packet.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>Note that the same <SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_packet_t</SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntin both the <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>_parse()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>_render()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntwith only a few modifications made
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntto the packet header's contents between uses. This method is recommended
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntas it keeps the serial, opcode, and other fields correct.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(1) When a packet is received, call <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="FUNCTION"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_*request_parse()</CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntunmarshall it. This returns a <SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_packet_t</SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt> (also called <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="VARNAME"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Huntas well as a data specific type, such as <SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>lwres_gabnrequest_t</SPAN
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(2) Process the request in the data specific type.</P
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan Hunt>(3) Set the <CODE
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"
28a4d32b05736e13299fb10c6c0addfa88c3cf87Evan HuntCLASS="STRUCTFIELD"