diff options
Diffstat (limited to '')
| -rw-r--r-- | lib/lwres/man/lwres.3 | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres.3 b/lib/lwres/man/lwres.3 new file mode 100644 index 0000000..61bed07 --- /dev/null +++ b/lib/lwres/man/lwres.3 @@ -0,0 +1,176 @@ +.\" Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.\" +.\" This Source Code Form is subject to the terms of the Mozilla Public +.\" License, v. 2.0. If a copy of the MPL was not distributed with this +.\" file, You can obtain one at http://mozilla.org/MPL/2.0/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: lwres +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "LWRES" "3" "2007\-06\-18" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +lwres \- introduction to the lightweight resolver library +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <lwres/lwres\&.h> +.fi +.ft +.SH "DESCRIPTION" +.PP +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 +\fBlwresd\fR +running on the local host\&. The resolver 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\&. +.SH "OVERVIEW" +.PP +The lwresd library implements multiple name service APIs\&. The standard +\fBgethostbyname()\fR, +\fBgethostbyaddr()\fR, +\fBgethostbyname_r()\fR, +\fBgethostbyaddr_r()\fR, +\fBgetaddrinfo()\fR, +\fBgetipnodebyname()\fR, and +\fBgetipnodebyaddr()\fR +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\&. +.PP +The library also provides a native API consisting of the functions +\fBlwres_getaddrsbyname()\fR +and +\fBlwres_getnamebyaddr()\fR\&. These may be called by applications that require more detailed control over the lookup process than the standard functions provide\&. +.PP +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 +\fBlwres_getaddrsbyname()\fR +function\&. +.PP +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 +\fBlwresd\fR +resolver daemon\&. The use of this low\-level API in clients and servers is outlined in the following sections\&. +.SH "CLIENT-SIDE LOW-LEVEL API CALL FLOW" +.PP +When a client program wishes to make an lwres request using the native low\-level API, it typically performs the following sequence of actions\&. +.PP +(1) Allocate or use an existing +\fBlwres_packet_t\fR, called +\fIpkt\fR +below\&. +.PP +(2) Set +\fIpkt\&.recvlength\fR +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: +\fBLWRES_RECVLENGTH = 4096\fR\&. +.PP +(3) Set +\fIpkt\&.serial\fR +to a unique serial number\&. This value is echoed back to the application by the remote server\&. +.PP +(4) Set +\fIpkt\&.pktflags\fR\&. Usually this is set to 0\&. +.PP +(5) Set +\fIpkt\&.result\fR +to 0\&. +.PP +(6) Call +\fBlwres_*request_render()\fR, or marshall in the data using the primitives such as +\fBlwres_packet_render()\fR +and storing the packet data\&. +.PP +(7) Transmit the resulting buffer\&. +.PP +(8) Call +\fBlwres_*response_parse()\fR +to parse any packets received\&. +.PP +(9) Verify that the opcode and serial match a request, and process the packet specific information contained in the body\&. +.SH "SERVER-SIDE LOW-LEVEL API CALL FLOW" +.PP +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\&. +.PP +Note that the same +\fBlwres_packet_t\fR +is used in both the +\fB_parse()\fR +and +\fB_render()\fR +calls, with only a few modifications made to the packet header\*(Aqs contents between uses\&. This method is recommended as it keeps the serial, opcode, and other fields correct\&. +.PP +(1) When a packet is received, call +\fBlwres_*request_parse()\fR +to unmarshall it\&. This returns a +\fBlwres_packet_t\fR +(also called +\fIpkt\fR, below) as well as a data specific type, such as +\fBlwres_gabnrequest_t\fR\&. +.PP +(2) Process the request in the data specific type\&. +.PP +(3) Set the +\fIpkt\&.result\fR, +\fIpkt\&.recvlength\fR +as above\&. All other fields can be left untouched since they were filled in by the +\fB*_parse()\fR +call above\&. If using +\fBlwres_*response_render()\fR, +\fIpkt\&.pktflags\fR +will be set up properly\&. Otherwise, the +\fBLWRES_LWPACKETFLAG_RESPONSE\fR +bit should be set\&. +.PP +(4) Call the data specific rendering function, such as +\fBlwres_gabnresponse_render()\fR\&. +.PP +(5) Send the resulting packet to the client\&. +.PP +.SH "SEE ALSO" +.PP +\fBlwres_gethostent\fR(3), +\fBlwres_getipnode\fR(3), +\fBlwres_getnameinfo\fR(3), +\fBlwres_noop\fR(3), +\fBlwres_gabn\fR(3), +\fBlwres_gnba\fR(3), +\fBlwres_context\fR(3), +\fBlwres_config\fR(3), +\fBresolver\fR(5), +\fBlwresd\fR(8)\&. +.SH "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.br |