Vender import of BIND 9.3.0rc4.

1 files changed, 188 insertions, 0 deletions

diff --git a/contrib/bind9/lib/lwres/man/lwres_gnba.3 b/contrib/bind9/lib/lwres/man/lwres_gnba.3
new file mode 100644
index 000000000000..404ae4141b02
--- /dev/null
+++ b/contrib/bind9/lib/lwres/man/lwres_gnba.3
@@ -0,0 +1,188 @@
+.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001  Internet Software Consortium.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" $Id: lwres_gnba.3,v 1.13.2.1.8.1 2004/03/06 07:41:43 marka Exp $
+.\"
+.TH "LWRES_GNBA" "3" "Jun 30, 2000" "BIND9" ""
+.SH NAME
+lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free \- lightweight resolver getnamebyaddress message handling
+.SH SYNOPSIS
+\fB#include <lwres/lwres.h>
+.sp
+.na
+lwres_result_t
+lwres_gnbarequest_render(lwres_context_t *\fIctx\fB, lwres_gnbarequest_t *\fIreq\fB, lwres_lwpacket_t *\fIpkt\fB, lwres_buffer_t *\fIb\fB);
+.ad
+.sp
+.na
+lwres_result_t
+lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
+.ad
+.sp
+.na
+lwres_result_t
+lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
+.ad
+.sp
+.na
+lwres_result_t
+lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp);
+.ad
+.sp
+.na
+void
+lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
+.ad
+.sp
+.na
+void
+lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
+.ad
+\fR
+.SH "DESCRIPTION"
+.PP
+These are low-level routines for creating and parsing
+lightweight resolver address-to-name lookup request and 
+response messages.
+.PP
+There are four main functions for the getnamebyaddr opcode.
+One render function converts a getnamebyaddr request structure \(em
+\fBlwres_gnbarequest_t\fR \(em
+to the lightweight resolver's canonical format.
+It is complemented by a parse function that converts a packet in this
+canonical format to a getnamebyaddr request structure.
+Another render function converts the getnamebyaddr response structure \(em
+\fBlwres_gnbaresponse_t\fR
+to the canonical format.
+This is complemented by a parse function which converts a packet in
+canonical format to a getnamebyaddr response structure.
+.PP
+These structures are defined in
+\fIlwres/lwres.h\fR.
+They are shown below.
+.sp
+.nf
+#define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
+
+typedef struct {
+        lwres_uint32_t  flags;
+        lwres_addr_t    addr;
+} lwres_gnbarequest_t;
+
+typedef struct {
+        lwres_uint32_t  flags;
+        lwres_uint16_t  naliases;
+        char           *realname;
+        char          **aliases;
+        lwres_uint16_t  realnamelen;
+        lwres_uint16_t *aliaslen;
+        void           *base;
+        size_t          baselen;
+} lwres_gnbaresponse_t;
+.sp
+.fi
+.PP
+\fBlwres_gnbarequest_render()\fR
+uses resolver context
+ctx
+to convert getnamebyaddr request structure
+req
+to canonical format.
+The packet header structure
+pkt
+is initialised and transferred to
+buffer
+b.
+The contents of
+*req
+are then appended to the buffer in canonical format.
+\fBlwres_gnbaresponse_render()\fR
+performs the same task, except it converts a getnamebyaddr response structure
+\fBlwres_gnbaresponse_t\fR
+to the lightweight resolver's canonical format.
+.PP
+\fBlwres_gnbarequest_parse()\fR
+uses context
+ctx
+to convert the contents of packet
+pkt
+to a
+\fBlwres_gnbarequest_t\fR
+structure.
+Buffer
+b
+provides space to be used for storing this structure.
+When the function succeeds, the resulting
+\fBlwres_gnbarequest_t\fR
+is made available through
+*structp.
+\fBlwres_gnbaresponse_parse()\fR
+offers the same semantics as
+\fBlwres_gnbarequest_parse()\fR
+except it yields a
+\fBlwres_gnbaresponse_t\fR
+structure.
+.PP
+\fBlwres_gnbaresponse_free()\fR
+and
+\fBlwres_gnbarequest_free()\fR
+release the memory in resolver context
+ctx
+that was allocated to the
+\fBlwres_gnbaresponse_t\fR
+or
+\fBlwres_gnbarequest_t\fR
+structures referenced via
+structp.
+Any memory associated with ancillary buffers and strings for those
+structures is also discarded.
+.SH "RETURN VALUES"
+.PP
+The getnamebyaddr opcode functions
+\fBlwres_gnbarequest_render()\fR,
+\fBlwres_gnbaresponse_render()\fR
+\fBlwres_gnbarequest_parse()\fR
+and
+\fBlwres_gnbaresponse_parse()\fR
+all return
+LWRES_R_SUCCESS
+on success.
+They return
+LWRES_R_NOMEMORY
+if memory allocation fails.
+LWRES_R_UNEXPECTEDEND
+is returned if the available space in the buffer
+b
+is too small to accommodate the packet header or the
+\fBlwres_gnbarequest_t\fR
+and
+\fBlwres_gnbaresponse_t\fR
+structures.
+\fBlwres_gnbarequest_parse()\fR
+and
+\fBlwres_gnbaresponse_parse()\fR
+will return
+LWRES_R_UNEXPECTEDEND
+if the buffer is not empty after decoding the received packet.
+These functions will return
+LWRES_R_FAILURE
+if
+\fBpktflags\fR
+in the packet header structure
+\fBlwres_lwpacket_t\fR
+indicate that the packet is not a response to an earlier query.
+.SH "SEE ALSO"
+.PP
+\fBlwres_packet\fR(3).