Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 255 insertions, 0 deletions

diff --git a/lib/lwres/man/lwres_gnba.docbook b/lib/lwres/man/lwres_gnba.docbook
new file mode 100644
index 0000000..72e5a1c
--- /dev/null
+++ b/lib/lwres/man/lwres_gnba.docbook
@@ -0,0 +1,255 @@
+<!DOCTYPE book [
+<!ENTITY mdash "&#8212;">]>
+<!--
+ - Copyright (C) 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/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
+  <info>
+    <date>2007-06-18</date>
+  </info>
+  <refentryinfo>
+    <corpname>ISC</corpname>
+    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>lwres_gnba</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>BIND9</refmiscinfo>
+  </refmeta>
+
+  <docinfo>
+    <copyright>
+      <year>2000</year>
+      <year>2001</year>
+      <year>2004</year>
+      <year>2005</year>
+      <year>2007</year>
+      <year>2014</year>
+      <year>2015</year>
+      <year>2016</year>
+      <year>2018</year>
+      <year>2019</year>
+      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+    </copyright>
+  </docinfo>
+
+  <refnamediv>
+    <refname>lwres_gnbarequest_render</refname>
+    <refname>lwres_gnbaresponse_render</refname>
+    <refname>lwres_gnbarequest_parse</refname>
+    <refname>lwres_gnbaresponse_parse</refname>
+    <refname>lwres_gnbaresponse_free</refname>
+    <refname>lwres_gnbarequest_free</refname>
+    <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;lwres/lwres.h&gt;
+</funcsynopsisinfo>
+
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gnbarequest_render</function>
+</funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
+        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        </funcprototype>
+
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gnbaresponse_render</function>
+</funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>
+        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gnbarequest_parse</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+        <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gnbaresponse_parse</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_gnbaresponse_free</function>
+</funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_gnbarequest_free</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
+      </funcprototype>
+</funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsection><info><title>DESCRIPTION</title></info>
+
+    <para>
+      These are low-level routines for creating and parsing
+      lightweight resolver address-to-name lookup request and
+      response messages.
+    </para>
+    <para>
+      There are four main functions for the getnamebyaddr opcode.
+      One render function converts a getnamebyaddr request structure &mdash;
+      <type>lwres_gnbarequest_t</type> &mdash;
+      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
+      &mdash;
+      <type>lwres_gnbaresponse_t</type>
+      to the canonical format.
+      This is complemented by a parse function which converts a packet in
+      canonical format to a getnamebyaddr response structure.
+    </para>
+    <para>
+      These structures are defined in
+      <filename>lwres/lwres.h</filename>.
+      They are shown below.
+    </para>
+    <para><programlisting>
+#define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint32_t  flags;
+        lwres_addr_t    addr;
+} lwres_gnbarequest_t;
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint32_t  flags;
+        uint16_t  naliases;
+        char           *realname;
+        char          **aliases;
+        uint16_t  realnamelen;
+        uint16_t *aliaslen;
+        void           *base;
+        size_t          baselen;
+} lwres_gnbaresponse_t;
+</programlisting>
+    </para>
+
+    <para><function>lwres_gnbarequest_render()</function>
+      uses resolver context <varname>ctx</varname> to convert
+      getnamebyaddr request structure <varname>req</varname> to
+      canonical format.  The packet header structure
+      <varname>pkt</varname> is initialised and transferred to buffer
+      <varname>b</varname>.  The contents of <varname>*req</varname>
+      are then appended to the buffer in canonical format.
+      <function>lwres_gnbaresponse_render()</function> performs the
+      same task, except it converts a getnamebyaddr response structure
+      <type>lwres_gnbaresponse_t</type> to the lightweight resolver's
+      canonical format.
+    </para>
+
+    <para><function>lwres_gnbarequest_parse()</function>
+      uses context <varname>ctx</varname> to convert the contents of
+      packet <varname>pkt</varname> to a
+      <type>lwres_gnbarequest_t</type> structure.  Buffer
+      <varname>b</varname> provides space to be used for storing this
+      structure.  When the function succeeds, the resulting
+      <type>lwres_gnbarequest_t</type> is made available through
+      <varname>*structp</varname>.
+      <function>lwres_gnbaresponse_parse()</function> offers the same
+      semantics as <function>lwres_gnbarequest_parse()</function>
+      except it yields a <type>lwres_gnbaresponse_t</type> structure.
+    </para>
+
+    <para><function>lwres_gnbaresponse_free()</function>
+      and <function>lwres_gnbarequest_free()</function> release the
+      memory in resolver context <varname>ctx</varname> that was
+      allocated to the <type>lwres_gnbaresponse_t</type> or
+      <type>lwres_gnbarequest_t</type> structures referenced via
+      <varname>structp</varname>.  Any memory associated with
+      ancillary buffers and strings for those structures is also
+      discarded.
+    </para>
+  </refsection>
+
+  <refsection><info><title>RETURN VALUES</title></info>
+
+    <para>
+      The getnamebyaddr opcode functions
+      <function>lwres_gnbarequest_render()</function>,
+      <function>lwres_gnbaresponse_render()</function>
+      <function>lwres_gnbarequest_parse()</function>
+      and
+      <function>lwres_gnbaresponse_parse()</function>
+      all return
+      <errorcode>LWRES_R_SUCCESS</errorcode>
+      on success.
+      They return
+      <errorcode>LWRES_R_NOMEMORY</errorcode>
+      if memory allocation fails.
+      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+      is returned if the available space in the buffer
+      <varname>b</varname>
+      is too small to accommodate the packet header or the
+      <type>lwres_gnbarequest_t</type>
+      and
+      <type>lwres_gnbaresponse_t</type>
+      structures.
+      <function>lwres_gnbarequest_parse()</function>
+      and
+      <function>lwres_gnbaresponse_parse()</function>
+      will return
+      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+      if the buffer is not empty after decoding the received packet.
+      These functions will return
+      <errorcode>LWRES_R_FAILURE</errorcode>
+      if
+      <varname remap="structfield">pktflags</varname>
+      in the packet header structure
+      <type>lwres_lwpacket_t</type>
+      indicate that the packet is not a response to an earlier query.
+    </para>
+  </refsection>
+  <refsection><info><title>SEE ALSO</title></info>
+
+    <para><citerefentry>
+        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+    </para>
+  </refsection>
+</refentry>