summaryrefslogtreecommitdiffstats
path: root/lib/lwres/man/lwres_resutil.docbook
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--lib/lwres/man/lwres_resutil.docbook230
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>