lwres_resutil.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!-- $Id: lwres_resutil.docbook,v 1.1 2001/03/31 00:08:23 gson Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refentrytitle>lwres_resutil</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver utility functions</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_string_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_addr_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint32_t addrtypes</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint32_t addrtype</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint16_t addrlen</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>const unsigned char *addr</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gnbaresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonretrieves a DNS-encoded string starting the current pointer of
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlightweight resolver buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the function returns, the address of the first byte of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonencoded string is returned via
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand the length of that string is given by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe buffer's current pointer is advanced to point at the character
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the string length, the encoded string, and the trailing
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonhas an assertion check that
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonextracts an address from the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe buffer's current pointer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis presumed to point at an encoded address: the address preceded by a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson32-bit protocol family identifier and a 16-bit length field.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe encoded address is copied to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindicates the size in bytes of the address that was copied.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis advanced to point at the next byte of available data in the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the encoded address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure defined below:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint32_t flags;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t naliases;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t naddrs;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char *realname;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char **aliases;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t realnamelen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t *aliaslen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_addrlist_t addrs;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson size_t baselen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnresponse_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of this structure are not manipulated directly but
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthey are controlled through the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lightweight resolver uses
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto perform foward lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis looked up using the resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor memory allocation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a bitmask indicating which type of addresses are to be looked up.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCurrent values for this bitmask are
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor IPv4 addresses and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor IPv6 addresses.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResults of the lookup are returned in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonchecks that its pointer arguments are not
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms reverse lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis used for memory allocation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe address type is indicated by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe address to be looked up is given by
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand its length is
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe result of the function call is made available through
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonuses assertion checking to ensure its pointer arguments are not
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonalso checks that
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBoth functions return
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer is corrupt or
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer has less space than expected for the components of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonencoded string or address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonon success and it returns
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncould not be found.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned by a successful call to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhen memory allocation requests fail and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffers used for sending queries and receiving replies are too
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.