lwres_resutil.docbook revision 194e2dfffa6a167b8eef0ad11864026b423a1c30
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
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 <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>