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, 254 insertions, 0 deletions

diff --git a/lib/lwres/man/lwres_gabn.docbook b/lib/lwres/man/lwres_gabn.docbook
new file mode 100644
index 0000000..4cff953
--- /dev/null
+++ b/lib/lwres/man/lwres_gabn.docbook
@@ -0,0 +1,254 @@
+<!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_gabn</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_gabnrequest_render</refname>
+    <refname>lwres_gabnresponse_render</refname>
+    <refname>lwres_gabnrequest_parse</refname>
+    <refname>lwres_gabnresponse_parse</refname>
+    <refname>lwres_gabnresponse_free</refname>
+    <refname>lwres_gabnrequest_free</refname>
+    <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gabnrequest_render</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gabnrequest_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_gabnresponse_render</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gabnresponse_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_gabnrequest_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_gabnrequest_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_gabnresponse_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_gabnresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_gabnresponse_free</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_gabnrequest_free</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_gabnrequest_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 name-to-address lookup request and
+      response messages.
+    </para>
+    <para>
+      There are four main functions for the getaddrbyname opcode.
+      One render function converts a getaddrbyname request structure &mdash;
+      <type>lwres_gabnrequest_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 getaddrbyname request structure.
+      Another render function converts the getaddrbyname response structure
+      &mdash; <type>lwres_gabnresponse_t</type> &mdash;
+      to the canonical format.
+      This is complemented by a parse function which converts a packet in
+      canonical format to a getaddrbyname response structure.
+    </para>
+    <para>
+      These structures are defined in
+      <filename>&lt;lwres/lwres.h&gt;</filename>.
+      They are shown below.
+    </para>
+    <para><programlisting>
+#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct lwres_addr lwres_addr_t;
+typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint32_t  flags;
+        uint32_t  addrtypes;
+        uint16_t  namelen;
+        char           *name;
+} lwres_gabnrequest_t;
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint32_t          flags;
+        uint16_t          naliases;
+        uint16_t          naddrs;
+        char                   *realname;
+        char                  **aliases;
+        uint16_t          realnamelen;
+        uint16_t         *aliaslen;
+        lwres_addrlist_t        addrs;
+        void                   *base;
+        size_t                  baselen;
+} lwres_gabnresponse_t;
+</programlisting>
+    </para>
+
+    <para><function>lwres_gabnrequest_render()</function>
+      uses resolver context <parameter>ctx</parameter> to convert
+      getaddrbyname request structure <parameter>req</parameter> to
+      canonical format.  The packet header structure
+      <parameter>pkt</parameter> is initialised and transferred to
+      buffer <parameter>b</parameter>.
+
+      The contents of <parameter>*req</parameter> are then appended to
+      the buffer in canonical format.
+      <function>lwres_gabnresponse_render()</function> performs the
+      same task, except it converts a getaddrbyname response structure
+      <type>lwres_gabnresponse_t</type> to the lightweight resolver's
+      canonical format.
+    </para>
+
+    <para><function>lwres_gabnrequest_parse()</function>
+      uses context <parameter>ctx</parameter> to convert the contents
+      of packet <parameter>pkt</parameter> to a
+      <type>lwres_gabnrequest_t</type> structure.  Buffer
+      <parameter>b</parameter> provides space to be used for storing
+      this structure.  When the function succeeds, the resulting
+      <type>lwres_gabnrequest_t</type> is made available through
+      <parameter>*structp</parameter>.
+
+      <function>lwres_gabnresponse_parse()</function> offers the same
+      semantics as <function>lwres_gabnrequest_parse()</function>
+      except it yields a <type>lwres_gabnresponse_t</type> structure.
+    </para>
+
+    <para><function>lwres_gabnresponse_free()</function>
+      and <function>lwres_gabnrequest_free()</function> release the
+      memory in resolver context <parameter>ctx</parameter> that was
+      allocated to the <type>lwres_gabnresponse_t</type> or
+      <type>lwres_gabnrequest_t</type> structures referenced via
+      <parameter>structp</parameter>.
+
+      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 getaddrbyname opcode functions
+      <function>lwres_gabnrequest_render()</function>,
+      <function>lwres_gabnresponse_render()</function>
+      <function>lwres_gabnrequest_parse()</function>
+      and
+      <function>lwres_gabnresponse_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
+      <parameter>b</parameter>
+      is too small to accommodate the packet header or the
+      <type>lwres_gabnrequest_t</type>
+      and
+      <type>lwres_gabnresponse_t</type>
+      structures.
+      <function>lwres_gabnrequest_parse()</function>
+      and
+      <function>lwres_gabnresponse_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>