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

diff --git a/lib/lwres/man/lwres_resutil.docbook b/lib/lwres/man/lwres_resutil.docbook
new file mode 100644
index 0000000..7ade2d9
--- /dev/null
+++ b/lib/lwres/man/lwres_resutil.docbook
@@ -0,0 +1,230 @@
+<!--
+ - 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_resutil</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_string_parse</refname>
+    <refname>lwres_addr_parse</refname>
+    <refname>lwres_getaddrsbyname</refname>
+    <refname>lwres_getnamebyaddr</refname>
+    <refpurpose>lightweight resolver utility functions</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_string_parse</function></funcdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        <paramdef>char **<parameter>c</parameter></paramdef>
+        <paramdef>uint16_t *<parameter>len</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_addr_parse</function></funcdef>
+        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+        <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_getaddrsbyname</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>const char *<parameter>name</parameter></paramdef>
+        <paramdef>uint32_t <parameter>addrtypes</parameter></paramdef>
+        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+lwres_result_t
+<function>lwres_getnamebyaddr</function></funcdef>
+        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+        <paramdef>uint32_t <parameter>addrtype</parameter></paramdef>
+        <paramdef>uint16_t <parameter>addrlen</parameter></paramdef>
+        <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
+        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
+      </funcprototype>
+</funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsection><info><title>DESCRIPTION</title></info>
+
+
+    <para><function>lwres_string_parse()</function>
+      retrieves a DNS-encoded string starting the current pointer of
+      lightweight resolver buffer <parameter>b</parameter>: i.e.
+      <constant>b-&gt;current</constant>.  When the function returns,
+      the address of the first byte of the encoded string is returned
+      via <parameter>*c</parameter> and the length of that string is
+      given by <parameter>*len</parameter>.  The buffer's current
+      pointer is advanced to point at the character following the
+      string length, the encoded string, and the trailing
+      <type>NULL</type> character.
+    </para>
+
+    <para><function>lwres_addr_parse()</function>
+      extracts an address from the buffer <parameter>b</parameter>.
+      The buffer's current pointer <constant>b-&gt;current</constant>
+      is presumed to point at an encoded address: the address preceded
+      by a 32-bit protocol family identifier and a 16-bit length
+      field.  The encoded address is copied to
+      <constant>addr-&gt;address</constant> and
+      <constant>addr-&gt;length</constant> indicates the size in bytes
+      of the address that was copied.
+      <constant>b-&gt;current</constant> is advanced to point at the
+      next byte of available data in the buffer following the encoded
+      address.
+    </para>
+
+    <para><function>lwres_getaddrsbyname()</function>
+      and <function>lwres_getnamebyaddr()</function> use the
+      <type>lwres_gnbaresponse_t</type> structure defined below:
+    </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>
+      The contents of this structure are not manipulated directly but
+      they are controlled through the
+      <citerefentry>
+        <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+      functions.
+    </para>
+
+    <para>
+      The lightweight resolver uses
+      <function>lwres_getaddrsbyname()</function> to perform
+      forward lookups.
+      Hostname <parameter>name</parameter> is looked up using the
+      resolver
+      context <parameter>ctx</parameter> for memory allocation.
+      <parameter>addrtypes</parameter> is a bitmask indicating
+      which type of
+      addresses are to be looked up.  Current values for this bitmask are
+      <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
+      <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses.  Results of the
+      lookup are returned in <parameter>*structp</parameter>.
+    </para>
+
+    <para><function>lwres_getnamebyaddr()</function>
+      performs reverse lookups.  Resolver context
+      <parameter>ctx</parameter> is used for memory allocation.  The
+      address type is indicated by <parameter>addrtype</parameter>:
+      <type>LWRES_ADDRTYPE_V4</type> or
+      <type>LWRES_ADDRTYPE_V6</type>.  The address to be looked up is
+      given by <parameter>addr</parameter> and its length is
+      <parameter>addrlen</parameter> bytes.  The result of the
+      function call is made available through
+      <parameter>*structp</parameter>.
+    </para>
+  </refsection>
+
+  <refsection><info><title>RETURN VALUES</title></info>
+
+    <para>
+      Successful calls to
+      <function>lwres_string_parse()</function>
+      and
+      <function>lwres_addr_parse()</function>
+      return
+      <errorcode>LWRES_R_SUCCESS.</errorcode>
+      Both functions return
+      <errorcode>LWRES_R_FAILURE</errorcode>
+      if the buffer is corrupt or
+      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+      if the buffer has less space than expected for the components of the
+      encoded string or address.
+    </para>
+
+    <para><function>lwres_getaddrsbyname()</function>
+      returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
+      returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
+      <parameter>name</parameter> could not be found.
+    </para>
+    <para><errorcode>LWRES_R_SUCCESS</errorcode>
+      is returned by a successful call to
+      <function>lwres_getnamebyaddr()</function>.
+    </para>
+
+    <para>
+      Both
+      <function>lwres_getaddrsbyname()</function>
+      and
+      <function>lwres_getnamebyaddr()</function>
+      return
+      <errorcode>LWRES_R_NOMEMORY</errorcode>
+      when memory allocation requests fail and
+      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+      if the buffers used for sending queries and receiving replies are too
+      small.
+    </para>
+
+  </refsection>
+  <refsection><info><title>SEE ALSO</title></info>
+
+    <para><citerefentry>
+        <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+    </para>
+
+  </refsection>
+</refentry>