lwres_resutil.html revision a24330c4805a224191ab687d0291963062fe3355
80833bb9a1bf25dcf19e814438a4b311d2e1f4cffuankg - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem - Copyright (C) 2000, 2001 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and/or distribute this software for any
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - purpose with or without fee is hereby granted, provided that the above
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
4da61833a1cbbca94094f9653fd970582b97a72etrawick - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
4da61833a1cbbca94094f9653fd970582b97a72etrawick - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
4da61833a1cbbca94094f9653fd970582b97a72etrawick - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
4789804be088bcd86ae637a29cdb7fda25169521jailletc - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
4789804be088bcd86ae637a29cdb7fda25169521jailletc - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
4789804be088bcd86ae637a29cdb7fda25169521jailletc - PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- $Id$ -->
5b88c8507d5ef6d0c4cfbc78230294968175b638minfrin<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
0a0df13b7f1f4f1a74fe295253d89ca3911b301aylavic<p>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions</p>
69301145375a889e7e37caf7cc7321ac0f91801erpluem<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
506bfe33206b2fece40ef25f695af39dd4130facjkaluzalwres_result_t
d58a848a016d401b965111e50ef829e1641f7834minfrin<b class="fsfunc">lwres_string_parse</b>(</code></td>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
d7205b1a86c51c27b71a2c458dc453fd53a261c1covenerlwres_result_t
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
caad2986f81ab263f7af41467dd622dc9add17f3ylaviclwres_result_t
caad2986f81ab263f7af41467dd622dc9add17f3ylavic<b class="fsfunc">lwres_getaddrsbyname</b>(</code></td>
09c87c777bed1655621bb20e1c46cb6b1a63279dcovener<var class="pdparam">structp</var><code>)</code>;</td>
3060ce7f798fbda7999cd4ddf89b525d2b294185covener<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
c1a63b8fad09c419c1a64f75993feb8a343a6801ylaviclwres_result_t
e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletc<b class="fsfunc">lwres_getnamebyaddr</b>(</code></td>
49dacedb6c387b786b7911082ff35121a45f414bcovener<var class="pdparam">structp</var><code>)</code>;</td>
fc42512879dd0504532f52fe5d0d0383dda96a1eniq retrieves a DNS-encoded string starting the current pointer of
fc42512879dd0504532f52fe5d0d0383dda96a1eniq lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e.
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq <code class="constant">b->current</code>. When the function returns,
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq the address of the first byte of the encoded string is returned
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niq via <em class="parameter"><code>*c</code></em> and the length of that string is
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc given by <em class="parameter"><code>*len</code></em>. The buffer's current
983528026996668ea295be95aedb9c7a346af470ylavic pointer is advanced to point at the character following the
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc string length, the encoded string, and the trailing
06b8f183140c8e02e0974e938a05078b511d1603covener extracts an address from the buffer <em class="parameter"><code>b</code></em>.
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem The buffer's current pointer <code class="constant">b->current</code>
259878293a997ff49f5ddfc53d3739cbdc25444ecovener is presumed to point at an encoded address: the address preceded
259878293a997ff49f5ddfc53d3739cbdc25444ecovener by a 32-bit protocol family identifier and a 16-bit length
259878293a997ff49f5ddfc53d3739cbdc25444ecovener field. The encoded address is copied to
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluem <code class="constant">addr->length</code> indicates the size in bytes
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin of the address that was copied.
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin <code class="constant">b->current</code> is advanced to point at the
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin next byte of available data in the buffer following the encoded
65967d05f839dbf27cf91d91fa79585eeae19660minfrin<p><code class="function">lwres_getaddrsbyname()</code>
65967d05f839dbf27cf91d91fa79585eeae19660minfrin and <code class="function">lwres_getnamebyaddr()</code> use the
8152945ae46857b170cb227e79bb799f4fc7710dminfrin <span class="type">lwres_gnbaresponse_t</span> structure defined below:
8152945ae46857b170cb227e79bb799f4fc7710dminfrintypedef struct {
75f5c2db254c0167a0e396254460de09b775d203trawick lwres_uint32_t flags;
75f5c2db254c0167a0e396254460de09b775d203trawick lwres_uint16_t naliases;
75f5c2db254c0167a0e396254460de09b775d203trawick lwres_uint16_t naddrs;
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph char *realname;
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph char **aliases;
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph lwres_uint16_t realnamelen;
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick lwres_uint16_t *aliaslen;
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick lwres_addrlist_t addrs;
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick void *base;
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick size_t baselen;
54d750a84a175d8e338880514d440773eb986b50covener} lwres_gabnresponse_t;
54d750a84a175d8e338880514d440773eb986b50covener The contents of this structure are not manipulated directly but
54d750a84a175d8e338880514d440773eb986b50covener they are controlled through the
54d750a84a175d8e338880514d440773eb986b50covener <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>
54d750a84a175d8e338880514d440773eb986b50covener The lightweight resolver uses
54d750a84a175d8e338880514d440773eb986b50covener <code class="function">lwres_getaddrsbyname()</code> to perform
83b50288fa7d306324bba68832011ea08f5c7832covener forward lookups.
4e30ef014533a7e93c92d88306291f5e49c9692ftrawick Hostname <em class="parameter"><code>name</code></em> is looked up using the
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick context <em class="parameter"><code>ctx</code></em> for memory allocation.
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating
5f066f496cd9f20a2a701255bc67d44e7cb46daetrawick which type of
2e15620d724fb8e3a5be183b917359a2fd6e9468covener addresses are to be looked up. Current values for this bitmask are
2e15620d724fb8e3a5be183b917359a2fd6e9468covener <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and
2e15620d724fb8e3a5be183b917359a2fd6e9468covener <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the
2e15620d724fb8e3a5be183b917359a2fd6e9468covener lookup are returned in <em class="parameter"><code>*structp</code></em>.
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener<p><code class="function">lwres_getnamebyaddr()</code>
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener performs reverse lookups. Resolver context
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener <em class="parameter"><code>ctx</code></em> is used for memory allocation. The
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener address type is indicated by <em class="parameter"><code>addrtype</code></em>:
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovener <span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd given by <em class="parameter"><code>addr</code></em> and its length is
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd <em class="parameter"><code>addrlen</code></em> bytes. The result of the
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd function call is made available through
fce4949fb0b309a5744afcd503c6ed2d35621ee2covener Successful calls to
ccc20788c1e5fc973f36df634399c89acb70deaejerenkrantz Both functions return
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza if the buffer is corrupt or
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluza if the buffer has less space than expected for the components of the
efe780dcf13b2b95effabf897d694d8f23feac74trawick encoded string or address.
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin<p><code class="function">lwres_getaddrsbyname()</code>
fe83f60b41477b14a37edcfcd1f7f5c5a1ebfe44minfrin returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname
993d1261a278d7322bccef219101220b7b4fb8c5jkaluza <em class="parameter"><code>name</code></em> could not be found.
ba050a6f942b9fa0e81ed73437588005c569655ccovener is returned by a successful call to
ba050a6f942b9fa0e81ed73437588005c569655ccovener <code class="function">lwres_getnamebyaddr()</code>.
001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh <code class="function">lwres_getnamebyaddr()</code>
793214f67dede32edfd9ee96c664ead04d175cbbjfclere when memory allocation requests fail and
cc5a4a08dc9783fcbc52ce86f11e01c281a43810minfrin <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovener if the buffers used for sending queries and receiving replies are too
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza<p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>,
56589be3d7a3e9343370df240010c6928cc78b39jkaluza <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>.