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

diff --git a/lib/lwres/man/lwres_noop.docbook b/lib/lwres/man/lwres_noop.docbook
new file mode 100644
index 0000000..64ab392
--- /dev/null
+++ b/lib/lwres/man/lwres_noop.docbook
@@ -0,0 +1,249 @@
+<!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_noop</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_nooprequest_render</refname>
+    <refname>lwres_noopresponse_render</refname>
+    <refname>lwres_nooprequest_parse</refname>
+    <refname>lwres_noopresponse_parse</refname>
+    <refname>lwres_noopresponse_free</refname>
+    <refname>lwres_nooprequest_free</refname>
+    <refpurpose>lightweight resolver no-op message handling</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_nooprequest_render</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_nooprequest_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_noopresponse_render</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_noopresponse_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_nooprequest_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_nooprequest_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_noopresponse_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_noopresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_noopresponse_free</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_nooprequest_free</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>lwres_nooprequest_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 no-op request and response messages.
+    </para>
+    <para>
+      The no-op message is analogous to a <command>ping</command>
+      packet:
+      a packet is sent to the resolver daemon and is simply echoed back.
+      The opcode is intended to allow a client to determine if the server is
+      operational or not.
+    </para>
+    <para>
+      There are four main functions for the no-op opcode.
+      One render function converts a no-op request structure &mdash;
+      <type>lwres_nooprequest_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 no-op request structure.
+      Another render function converts the no-op response structure &mdash;
+      <type>lwres_noopresponse_t</type>
+      to the canonical format.
+      This is complemented by a parse function which converts a packet in
+      canonical format to a no-op response structure.
+    </para>
+    <para>
+      These structures are defined in
+      <filename>lwres/lwres.h</filename>.
+
+      They are shown below.
+    </para>
+    <para><programlisting>
+#define LWRES_OPCODE_NOOP       0x00000000U
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint16_t  datalength;
+        unsigned char   *data;
+} lwres_nooprequest_t;
+</programlisting>
+    </para>
+    <para><programlisting>
+typedef struct {
+        uint16_t  datalength;
+        unsigned char   *data;
+} lwres_noopresponse_t;
+</programlisting>
+    </para>
+    <para>
+      Although the structures have different types, they are identical.
+      This is because the no-op opcode simply echos whatever data was sent:
+      the response is therefore identical to the request.
+    </para>
+
+    <para><function>lwres_nooprequest_render()</function>
+      uses resolver context <parameter>ctx</parameter> to convert
+      no-op 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_noopresponse_render()</function> performs the
+      same task, except it converts a no-op response structure
+      <type>lwres_noopresponse_t</type> to the lightweight resolver's
+      canonical format.
+    </para>
+
+    <para><function>lwres_nooprequest_parse()</function>
+      uses context <parameter>ctx</parameter> to convert the contents
+      of packet <parameter>pkt</parameter> to a
+      <type>lwres_nooprequest_t</type> structure.  Buffer
+      <parameter>b</parameter> provides space to be used for storing
+      this structure.  When the function succeeds, the resulting
+      <type>lwres_nooprequest_t</type> is made available through
+      <parameter>*structp</parameter>.
+      <function>lwres_noopresponse_parse()</function> offers the same
+      semantics as <function>lwres_nooprequest_parse()</function>
+      except it yields a <type>lwres_noopresponse_t</type> structure.
+    </para>
+
+    <para><function>lwres_noopresponse_free()</function>
+      and <function>lwres_nooprequest_free()</function> release the
+      memory in resolver context <parameter>ctx</parameter> that was
+      allocated to the <type>lwres_noopresponse_t</type> or
+      <type>lwres_nooprequest_t</type> structures referenced via
+      <parameter>structp</parameter>.
+    </para>
+
+  </refsection>
+  <refsection><info><title>RETURN VALUES</title></info>
+
+    <para>
+      The no-op opcode functions
+      <function>lwres_nooprequest_render()</function>,
+
+      <function>lwres_noopresponse_render()</function>
+      <function>lwres_nooprequest_parse()</function>
+      and
+      <function>lwres_noopresponse_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_nooprequest_t</type>
+      and
+      <type>lwres_noopresponse_t</type>
+      structures.
+      <function>lwres_nooprequest_parse()</function>
+      and
+      <function>lwres_noopresponse_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
+      <constant>pktflags</constant>
+      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>