Date: Thu, 12 Apr 2007 20:30:08 +0000 Subject: [svn-upgrade] Integrating new upstream version, strongswan (4.1.1) --- lib/liblwres/man/lwres.html | 444 -------------------------------------------- 1 file changed, 444 deletions(-) delete mode 100644 lib/liblwres/man/lwres.html (limited to 'lib/liblwres/man/lwres.html') diff --git a/lib/liblwres/man/lwres.html b/lib/liblwres/man/lwres.html deleted file mode 100644 index 7b9f88dcb..000000000 --- a/lib/liblwres/man/lwres.html +++ /dev/null @@ -1,444 +0,0 @@ - -lwres

lwres

Name

lwres -- introduction to the lightweight resolver library

Synopsis

#include <lwres/lwres.h>

DESCRIPTION

The BIND 9 lightweight resolver library is a simple, name service -independent stub resolver library. It provides hostname-to-address -and address-to-hostname lookup services to applications by -transmitting lookup requests to a resolver daemon -lwresd -running on the local host. The resover daemon performs the -lookup using the DNS or possibly other name service protocols, -and returns the results to the application through the library. -The library and resolver daemon communicate using a simple -UDP-based protocol.

OVERVIEW

The lwresd library implements multiple name service APIs. -The standard -gethostbyname(), -gethostbyaddr(), -gethostbyname_r(), -gethostbyaddr_r(), -getaddrinfo(), -getipnodebyname(), -and -getipnodebyaddr() -functions are all supported. To allow the lwres library to coexist -with system libraries that define functions of the same name, -the library defines these functions with names prefixed by -lwres_. -To define the standard names, applications must include the -header file -<lwres/netdb.h> -which contains macro definitions mapping the standard function names -into -lwres_ -prefixed ones. Operating system vendors who integrate the lwres -library into their base distributions should rename the functions -in the library proper so that the renaming macros are not needed.

The library also provides a native API consisting of the functions -lwres_getaddrsbyname() -and -lwres_getnamebyaddr(). -These may be called by applications that require more detailed -control over the lookup process than the standard functions -provide.

In addition to these name service independent address lookup -functions, the library implements a new, experimental API -for looking up arbitrary DNS resource records, using the -lwres_getaddrsbyname() -function.

Finally, there is a low-level API for converting lookup -requests and responses to and from raw lwres protocol packets. -This API can be used by clients requiring nonblocking operation, -and is also used when implementing the server side of the lwres -protocol, for example in the -lwresd -resolver daemon. The use of this low-level API in clients -and servers is outlined in the following sections.

CLIENT-SIDE LOW-LEVEL API CALL FLOW

When a client program wishes to make an lwres request using the -native low-level API, it typically performs the following -sequence of actions.

(1) Allocate or use an existing lwres_packet_t, -called pkt below.

(2) Set pkt.recvlength to the maximum length we will accept. -This is done so the receiver of our packets knows how large our receive -buffer is. The "default" is a constant in -lwres.h: LWRES_RECVLENGTH = 4096.

(3) Set pkt.serial -to a unique serial number. This value is echoed -back to the application by the remote server.

(4) Set pkt.pktflags. Usually this is set to 0.

(5) Set pkt.result to 0.

(6) Call lwres_*request_render(), -or marshall in the data using the primitives -such as lwres_packet_render() -and storing the packet data.

(7) Transmit the resulting buffer.

(8) Call lwres_*response_parse() -to parse any packets received.

(9) Verify that the opcode and serial match a request, and process the -packet specific information contained in the body.

SERVER-SIDE LOW-LEVEL API CALL FLOW

When implementing the server side of the lightweight resolver -protocol using the lwres library, a sequence of actions like the -following is typically involved in processing each request packet.

Note that the same lwres_packet_t is used -in both the _parse() and _render() calls, -with only a few modifications made -to the packet header's contents between uses. This method is recommended -as it keeps the serial, opcode, and other fields correct.

(1) When a packet is received, call lwres_*request_parse() to -unmarshall it. This returns a lwres_packet_t (also called pkt, below) -as well as a data specific type, such as lwres_gabnrequest_t.

(2) Process the request in the data specific type.

(3) Set the pkt.result, -pkt.recvlength as above. All other fields can -be left untouched since they were filled in by the *_parse() call -above. If using lwres_*response_render(), -pkt.pktflags will be set up -properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be -set.

(4) Call the data specific rendering function, such as -lwres_gabnresponse_render().

(5) Send the resulting packet to the client.