lwres_resutil.docbook revision 268a4475065fe6a8cd7cc707820982cf5e98f430
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem [<!ENTITY mdash "—">]>
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Copyright (C) 2000, 2001 Internet Software Consortium.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - Permission to use, copy, modify, and distribute this software for any
4da61833a1cbbca94094f9653fd970582b97a72etrawick - purpose with or without fee is hereby granted, provided that the above
4da61833a1cbbca94094f9653fd970582b97a72etrawick - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
4789804be088bcd86ae637a29cdb7fda25169521jailletc - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
4789804be088bcd86ae637a29cdb7fda25169521jailletc - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
4789804be088bcd86ae637a29cdb7fda25169521jailletc - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
e50c3026198fd496f183cda4c32a202925476778covener - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
e50c3026198fd496f183cda4c32a202925476778covener - PERFORMANCE OF THIS SOFTWARE.
5b88c8507d5ef6d0c4cfbc78230294968175b638minfrin<!-- $Id: lwres_resutil.docbook,v 1.8 2005/05/11 05:55:41 sra Exp $ -->
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic <refentryinfo>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic </refentryinfo>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza <copyright>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
d58a848a016d401b965111e50ef829e1641f7834minfrin </copyright>
d58a848a016d401b965111e50ef829e1641f7834minfrin <copyright>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf </copyright>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic <refnamediv>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic <refpurpose>lightweight resolver utility functions</refpurpose>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic </refnamediv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <refsynopsisdiv>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic <funcsynopsis>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylaviclwres_result_t
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>char **<parameter>c</parameter></paramdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener </funcprototype>
44ff304057225e944e220e981d434a046d14cf06covener<funcprototype>
44ff304057225e944e220e981d434a046d14cf06covenerlwres_result_t
5d1ba75b8794925e67591c209085a49279791de9covener <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
5d1ba75b8794925e67591c209085a49279791de9covener <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
5d1ba75b8794925e67591c209085a49279791de9covener </funcprototype>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand<funcprototype>
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrandlwres_result_t
caad2986f81ab263f7af41467dd622dc9add17f3ylavic <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic <paramdef>const char *<parameter>name</parameter></paramdef>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
caad2986f81ab263f7af41467dd622dc9add17f3ylavic <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
45a10d38e6051fd7bdf9d742aaae633d97ff02abjailletc </funcprototype>
f7317ff316c2b141feea31bddb74d5d3fa1584edjorton<funcprototype>
2165214331e4afafca4048f66f303d0253d7b001covenerlwres_result_t
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
1e2d421a36999d292042a5539971070d54aa6c63ylavic <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
1e2d421a36999d292042a5539971070d54aa6c63ylavic <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
1e2d421a36999d292042a5539971070d54aa6c63ylavic <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh </funcprototype>
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh</funcsynopsis>
0b67eb8568cd58bb77082703951679b42cf098actrawick </refsynopsisdiv>
09c87c777bed1655621bb20e1c46cb6b1a63279dcovener retrieves a DNS-encoded string starting the current pointer of
6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavic lightweight resolver buffer <parameter>b</parameter>: i.e.
6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavic <constant>b->current</constant>. When the function returns,
3060ce7f798fbda7999cd4ddf89b525d2b294185covener the address of the first byte of the encoded string is returned
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic via <parameter>*c</parameter> and the length of that string is
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic given by <parameter>*len</parameter>. The buffer's current
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic pointer is advanced to point at the character following the
e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletc string length, the encoded string, and the trailing
457468b82e59d01eba00dd9d0817309c8f5e414ejim extracts an address from the buffer <parameter>b</parameter>.
457468b82e59d01eba00dd9d0817309c8f5e414ejim The buffer's current pointer <constant>b->current</constant>
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton is presumed to point at an encoded address: the address preceded
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton by a 32-bit protocol family identifier and a 16-bit length
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem field. The encoded address is copied to
15660979a30d251681463de2e0584853890082accovener <constant>addr->length</constant> indicates the size in bytes
49dacedb6c387b786b7911082ff35121a45f414bcovener of the address that was copied.
49dacedb6c387b786b7911082ff35121a45f414bcovener <constant>b->current</constant> is advanced to point at the
cfd9415521847b2f9394fad04fb701cfb955f503rjung next byte of available data in the buffer following the encoded
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe and <function>lwres_getnamebyaddr()</function> use the
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe <type>lwres_gnbaresponse_t</type> structure defined below:
63b9f1f5880391261705f696d7d65507bbe9ace3covenertypedef struct {
63b9f1f5880391261705f696d7d65507bbe9ace3covener lwres_uint32_t flags;
49dacedb6c387b786b7911082ff35121a45f414bcovener lwres_uint16_t naliases;
49dacedb6c387b786b7911082ff35121a45f414bcovener lwres_uint16_t naddrs;
49dacedb6c387b786b7911082ff35121a45f414bcovener char *realname;
49dacedb6c387b786b7911082ff35121a45f414bcovener char **aliases;
3c990331fc6702119e4f5b8ba9eae3021aea5265jim lwres_uint16_t realnamelen;
3c990331fc6702119e4f5b8ba9eae3021aea5265jim lwres_uint16_t *aliaslen;
3c990331fc6702119e4f5b8ba9eae3021aea5265jim lwres_addrlist_t addrs;
3c990331fc6702119e4f5b8ba9eae3021aea5265jim void *base;
fc42512879dd0504532f52fe5d0d0383dda96a1eniq size_t baselen;
fc42512879dd0504532f52fe5d0d0383dda96a1eniq} lwres_gabnresponse_t;
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq The contents of this structure are not manipulated directly but
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc they are controlled through the
983528026996668ea295be95aedb9c7a346af470ylavic <citerefentry>
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc </citerefentry>
259878293a997ff49f5ddfc53d3739cbdc25444ecovener The lightweight resolver uses
259878293a997ff49f5ddfc53d3739cbdc25444ecovener <function>lwres_getaddrsbyname()</function> to perform
259878293a997ff49f5ddfc53d3739cbdc25444ecovener foward lookups.
259878293a997ff49f5ddfc53d3739cbdc25444ecovener Hostname <parameter>name</parameter> is looked up using the
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin context <parameter>ctx</parameter> for memory allocation.
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin <parameter>addrtypes</parameter> is a bitmask indicating
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin which type of
65967d05f839dbf27cf91d91fa79585eeae19660minfrin addresses are to be looked up. Current values for this bitmask are
65967d05f839dbf27cf91d91fa79585eeae19660minfrin <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
65967d05f839dbf27cf91d91fa79585eeae19660minfrin <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
65967d05f839dbf27cf91d91fa79585eeae19660minfrin lookup are returned in <parameter>*structp</parameter>.
8152945ae46857b170cb227e79bb799f4fc7710dminfrin performs reverse lookups. Resolver context
75f5c2db254c0167a0e396254460de09b775d203trawick <parameter>ctx</parameter> is used for memory allocation. The
75f5c2db254c0167a0e396254460de09b775d203trawick address type is indicated by <parameter>addrtype</parameter>:
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph given by <parameter>addr</parameter> and its length is
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph <parameter>addrlen</parameter> bytes. The result of the
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick function call is made available through
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick </refsect1>
54d750a84a175d8e338880514d440773eb986b50covener Successful calls to
54d750a84a175d8e338880514d440773eb986b50covener Both functions return
4e30ef014533a7e93c92d88306291f5e49c9692ftrawick if the buffer is corrupt or
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick if the buffer has less space than expected for the components of the
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick encoded string or address.
2e15620d724fb8e3a5be183b917359a2fd6e9468covener returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
2e15620d724fb8e3a5be183b917359a2fd6e9468covener returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener is returned by a successful call to
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener when memory allocation requests fail and
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener if the buffers used for sending queries and receiving replies are too
7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawick </refsect1>
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza </citerefentry>,
efe780dcf13b2b95effabf897d694d8f23feac74trawick <citerefentry>
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin </citerefentry>.
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza </refsect1>
ba050a6f942b9fa0e81ed73437588005c569655ccovener - Local variables:
ba050a6f942b9fa0e81ed73437588005c569655ccovener - mode: sgml