1 files changed, 149 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_packet.3 b/lib/liblwres/man/lwres_packet.3
new file mode 100644
index 000000000..d7fb6f077
--- /dev/null
+++ b/lib/liblwres/man/lwres_packet.3
@@ -0,0 +1,149 @@
+.\"
+.\" 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 INTERNET SOFTWARE CONSORTIUM
+.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+.\" INTERNET SOFTWARE CONSORTIUM 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.
+.\"
+.TH "LWRES_PACKET" "3" "Jun 30, 2000" "BIND9" ""
+.SH NAME
+lwres_lwpacket_renderheader, lwres_lwpacket_parseheader \- lightweight resolver packet handling functions
+.SH SYNOPSIS
+\fB#include <lwres/lwpacket.h>
+.sp
+.na
+lwres_result_t
+lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
+.ad
+.sp
+.na
+lwres_result_t
+lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
+.ad
+\fR.SH "DESCRIPTION"
+.PP
+These functions rely on a
+\fBstruct lwres_lwpacket\fR
+which is defined in
+\fIlwres/lwpacket.h\fR.
+.sp
+.nf
+typedef struct lwres_lwpacket lwres_lwpacket_t;
+
+struct lwres_lwpacket {
+        lwres_uint32_t          length;
+        lwres_uint16_t          version;
+        lwres_uint16_t          pktflags;
+        lwres_uint32_t          serial;
+        lwres_uint32_t          opcode;
+        lwres_uint32_t          result;
+        lwres_uint32_t          recvlength;
+        lwres_uint16_t          authtype;
+        lwres_uint16_t          authlength;
+};
+.sp
+.fi
+.PP
+The elements of this structure are:
+.TP
+\fBlength\fR
+the overall packet length, including the entire packet header.
+This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+calls.
+.TP
+\fBversion\fR
+the header format. There is currently only one format,
+\fBLWRES_LWPACKETVERSION_0\fR.
+This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+calls.
+.TP
+\fBpktflags\fR
+library-defined flags for this packet: for instance whether the packet
+is a request or a reply. Flag values can be set, but not defined by
+the caller.
+This field is filled in by the application wit the exception of the
+LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
+lwres_gabn_*() and lwres_gnba_*() calls.
+.TP
+\fBserial\fR
+is set by the requestor and is returned in all replies. If two or more
+packets from the same source have the same serial number and are from
+the same source, they are assumed to be duplicates and the latter ones
+may be dropped.
+This field must be set by the application.
+.TP
+\fBopcode\fR
+indicates the operation.
+Opcodes between 0x00000000 and 0x03ffffff are
+reserved for use by the lightweight resolver library. Opcodes between
+0x04000000 and 0xffffffff are application defined.
+This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+calls.
+.TP
+\fBresult\fR
+is only valid for replies.
+Results between 0x04000000 and 0xffffffff are application defined.
+Results between 0x00000000 and 0x03ffffff are reserved for library use.
+This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
+calls.
+.TP
+\fBrecvlength\fR
+is the maximum buffer size that the receiver can handle on requests
+and the size of the buffer needed to satisfy a request when the buffer
+is too large for replies.
+This field is supplied by the application.
+.TP
+\fBauthtype\fR
+defines the packet level authentication that is used.
+Authorisation types between 0x1000 and 0xffff are application defined
+and types between 0x0000 and 0x0fff are reserved for library use.
+Currently these are not used and must be zero.
+.TP
+\fBauthlen\fR
+gives the length of the authentication data.
+Since packet authentication is currently not used, this must be zero.
+.PP
+The following opcodes are currently defined:
+.TP
+\fBNOOP\fR
+Success is always returned and the packet contents are echoed.
+The lwres_noop_*() functions should be used for this type.
+.TP
+\fBGETADDRSBYNAME\fR
+returns all known addresses for a given name.
+The lwres_gabn_*() functions should be used for this type.
+.TP
+\fBGETNAMEBYADDR\fR
+return the hostname for the given address.
+The lwres_gnba_*() functions should be used for this type.
+.PP
+\fBlwres_lwpacket_renderheader()\fR transfers the
+contents of lightweight resolver packet structure
+\fBlwres_lwpacket_t\fR \fI*pkt\fR in network
+byte order to the lightweight resolver buffer,
+\fI*b\fR.
+.PP
+\fBlwres_lwpacket_parseheader()\fR performs the
+converse operation. It transfers data in network byte order from
+buffer \fI*b\fR to resolver packet
+\fI*pkt\fR. The contents of the buffer
+\fIb\fR should correspond to a
+\fBlwres_lwpacket_t\fR.
+.SH "RETURN VALUES"
+.PP
+Successful calls to
+\fBlwres_lwpacket_renderheader()\fR and
+\fBlwres_lwpacket_parseheader()\fR return
+LWRES_R_SUCCESS. If there is insufficient
+space to copy data between the buffer \fI*b\fR and
+lightweight resolver packet \fI*pkt\fR both functions
+return LWRES_R_UNEXPECTEDEND.