lwres_resutil.docbook revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
938440694b33cd752e9e4b71a526368b4811c177Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver utility functions</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_string_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>char **<parameter>c</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_addr_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const char *<parameter>name</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein retrieves a DNS-encoded string starting the current pointer of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver buffer <parameter>b</parameter>: i.e.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>b->current</constant>. When the function returns,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the address of the first byte of the encoded string is returned
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein via <parameter>*c</parameter> and the length of that string is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein given by <parameter>*len</parameter>. The buffer's current
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein pointer is advanced to point at the character following the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein string length, the encoded string, and the trailing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein extracts an address from the buffer <parameter>b</parameter>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The buffer's current pointer <constant>b->current</constant>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is presumed to point at an encoded address: the address preceded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein by a 32-bit protocol family identifier and a 16-bit length
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein field. The encoded address is copied to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>addr->length</constant> indicates the size in bytes
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of the address that was copied.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>b->current</constant> is advanced to point at the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein next byte of available data in the buffer following the encoded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getaddrsbyname()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and <function>lwres_getnamebyaddr()</function> use the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbaresponse_t</type> structure defined below:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naddrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addrlist_t addrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t baselen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnresponse_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The contents of this structure are not manipulated directly but
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein they are controlled through the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lightweight resolver uses
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_getaddrsbyname()</function> to perform
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed forward lookups.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Hostname <parameter>name</parameter> is looked up using the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein context <parameter>ctx</parameter> for memory allocation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>addrtypes</parameter> is a bitmask indicating
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which type of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein addresses are to be looked up. Current values for this bitmask are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lookup are returned in <parameter>*structp</parameter>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getnamebyaddr()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein performs reverse lookups. Resolver context
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>ctx</parameter> is used for memory allocation. The
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein address type is indicated by <parameter>addrtype</parameter>:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein given by <parameter>addr</parameter> and its length is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>addrlen</parameter> bytes. The result of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein function call is made available through
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Successful calls to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Both functions return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer is corrupt or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer has less space than expected for the components of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein encoded string or address.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getaddrsbyname()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned by a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein when memory allocation requests fail and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffers used for sending queries and receiving replies are too
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>