lwres_resutil.html revision 5347c0fcb04eaea19d9f39795646239f487c6207
0c04407550130c0ea040b5675f2c214426b27718fuankg - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c04407550130c0ea040b5675f2c214426b27718fuankg - This Source Code Form is subject to the terms of the Mozilla Public
0c04407550130c0ea040b5675f2c214426b27718fuankg - License, v. 2.0. If a copy of the MPL was not distributed with this
0c04407550130c0ea040b5675f2c214426b27718fuankg - file, You can obtain one at http://mozilla.org/MPL/2.0/.
0c04407550130c0ea040b5675f2c214426b27718fuankg<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0c04407550130c0ea040b5675f2c214426b27718fuankg<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
0c04407550130c0ea040b5675f2c214426b27718fuankg<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
0c04407550130c0ea040b5675f2c214426b27718fuankg<p>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions</p>
16b55a35cff91315d261d1baa776138af465c4e4fuankg<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
0c04407550130c0ea040b5675f2c214426b27718fuankg<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
0c04407550130c0ea040b5675f2c214426b27718fuankglwres_result_t
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_uint16_t *<var class="pdparam">len</var><code>)</code>;</td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
0c04407550130c0ea040b5675f2c214426b27718fuankglwres_result_t
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_addr_t *<var class="pdparam">addr</var><code>)</code>;</td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
0c04407550130c0ea040b5675f2c214426b27718fuankglwres_result_t
0c04407550130c0ea040b5675f2c214426b27718fuankg<b class="fsfunc">lwres_getaddrsbyname</b>(</code></td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>const char *<var class="pdparam">name</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_uint32_t <var class="pdparam">addrtypes</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_gabnresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
0c04407550130c0ea040b5675f2c214426b27718fuankglwres_result_t
0c04407550130c0ea040b5675f2c214426b27718fuankg<b class="fsfunc">lwres_getnamebyaddr</b>(</code></td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_uint32_t <var class="pdparam">addrtype</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_uint16_t <var class="pdparam">addrlen</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>const unsigned char *<var class="pdparam">addr</var>, </td>
0c04407550130c0ea040b5675f2c214426b27718fuankg<td>lwres_gnbaresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
0c04407550130c0ea040b5675f2c214426b27718fuankg retrieves a DNS-encoded string starting the current pointer of
0c04407550130c0ea040b5675f2c214426b27718fuankg lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e.
0c04407550130c0ea040b5675f2c214426b27718fuankg <code class="constant">b->current</code>. When the function returns,
0c04407550130c0ea040b5675f2c214426b27718fuankg the address of the first byte of the encoded string is returned
0c04407550130c0ea040b5675f2c214426b27718fuankg via <em class="parameter"><code>*c</code></em> and the length of that string is
0c04407550130c0ea040b5675f2c214426b27718fuankg given by <em class="parameter"><code>*len</code></em>. The buffer's current
0662ed52e814f8f08ef0e09956413a792584eddffuankg pointer is advanced to point at the character following the
0c04407550130c0ea040b5675f2c214426b27718fuankg string length, the encoded string, and the trailing
0c04407550130c0ea040b5675f2c214426b27718fuankg extracts an address from the buffer <em class="parameter"><code>b</code></em>.
0c04407550130c0ea040b5675f2c214426b27718fuankg The buffer's current pointer <code class="constant">b->current</code>
0c04407550130c0ea040b5675f2c214426b27718fuankg is presumed to point at an encoded address: the address preceded
0c04407550130c0ea040b5675f2c214426b27718fuankg by a 32-bit protocol family identifier and a 16-bit length
0c04407550130c0ea040b5675f2c214426b27718fuankg field. The encoded address is copied to
0c04407550130c0ea040b5675f2c214426b27718fuankg <code class="constant">addr->length</code> indicates the size in bytes
0c04407550130c0ea040b5675f2c214426b27718fuankg of the address that was copied.
0662ed52e814f8f08ef0e09956413a792584eddffuankg <code class="constant">b->current</code> is advanced to point at the
0c04407550130c0ea040b5675f2c214426b27718fuankg next byte of available data in the buffer following the encoded
0c04407550130c0ea040b5675f2c214426b27718fuankg<p><code class="function">lwres_getaddrsbyname()</code>
0662ed52e814f8f08ef0e09956413a792584eddffuankg and <code class="function">lwres_getnamebyaddr()</code> use the
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="type">lwres_gnbaresponse_t</span> structure defined below:
0c04407550130c0ea040b5675f2c214426b27718fuankgtypedef struct {
0c04407550130c0ea040b5675f2c214426b27718fuankg lwres_uint32_t flags;
0c04407550130c0ea040b5675f2c214426b27718fuankg lwres_uint16_t naliases;
0c04407550130c0ea040b5675f2c214426b27718fuankg lwres_uint16_t naddrs;
0c04407550130c0ea040b5675f2c214426b27718fuankg char *realname;
0c04407550130c0ea040b5675f2c214426b27718fuankg char **aliases;
0662ed52e814f8f08ef0e09956413a792584eddffuankg lwres_uint16_t realnamelen;
0c04407550130c0ea040b5675f2c214426b27718fuankg lwres_uint16_t *aliaslen;
0c04407550130c0ea040b5675f2c214426b27718fuankg lwres_addrlist_t addrs;
0c04407550130c0ea040b5675f2c214426b27718fuankg void *base;
0c04407550130c0ea040b5675f2c214426b27718fuankg size_t baselen;
0c04407550130c0ea040b5675f2c214426b27718fuankg} lwres_gabnresponse_t;
0c04407550130c0ea040b5675f2c214426b27718fuankg The contents of this structure are not manipulated directly but
0c04407550130c0ea040b5675f2c214426b27718fuankg they are controlled through the
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>
0c04407550130c0ea040b5675f2c214426b27718fuankg The lightweight resolver uses
0c04407550130c0ea040b5675f2c214426b27718fuankg <code class="function">lwres_getaddrsbyname()</code> to perform
0c04407550130c0ea040b5675f2c214426b27718fuankg forward lookups.
0c04407550130c0ea040b5675f2c214426b27718fuankg Hostname <em class="parameter"><code>name</code></em> is looked up using the
0c04407550130c0ea040b5675f2c214426b27718fuankg context <em class="parameter"><code>ctx</code></em> for memory allocation.
0c04407550130c0ea040b5675f2c214426b27718fuankg <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating
0c04407550130c0ea040b5675f2c214426b27718fuankg which type of
0c04407550130c0ea040b5675f2c214426b27718fuankg addresses are to be looked up. Current values for this bitmask are
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the
0c04407550130c0ea040b5675f2c214426b27718fuankg lookup are returned in <em class="parameter"><code>*structp</code></em>.
0c04407550130c0ea040b5675f2c214426b27718fuankg<p><code class="function">lwres_getnamebyaddr()</code>
0c04407550130c0ea040b5675f2c214426b27718fuankg performs reverse lookups. Resolver context
0c04407550130c0ea040b5675f2c214426b27718fuankg <em class="parameter"><code>ctx</code></em> is used for memory allocation. The
0c04407550130c0ea040b5675f2c214426b27718fuankg address type is indicated by <em class="parameter"><code>addrtype</code></em>:
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is
0c04407550130c0ea040b5675f2c214426b27718fuankg given by <em class="parameter"><code>addr</code></em> and its length is
0c04407550130c0ea040b5675f2c214426b27718fuankg <em class="parameter"><code>addrlen</code></em> bytes. The result of the
0c04407550130c0ea040b5675f2c214426b27718fuankg function call is made available through
0c04407550130c0ea040b5675f2c214426b27718fuankg Successful calls to
0c04407550130c0ea040b5675f2c214426b27718fuankg Both functions return
0c04407550130c0ea040b5675f2c214426b27718fuankg if the buffer is corrupt or
0c04407550130c0ea040b5675f2c214426b27718fuankg if the buffer has less space than expected for the components of the
0c04407550130c0ea040b5675f2c214426b27718fuankg encoded string or address.
0c04407550130c0ea040b5675f2c214426b27718fuankg<p><code class="function">lwres_getaddrsbyname()</code>
0c04407550130c0ea040b5675f2c214426b27718fuankg returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it
0c04407550130c0ea040b5675f2c214426b27718fuankg returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname
0c04407550130c0ea040b5675f2c214426b27718fuankg <em class="parameter"><code>name</code></em> could not be found.
0c04407550130c0ea040b5675f2c214426b27718fuankg is returned by a successful call to
0c04407550130c0ea040b5675f2c214426b27718fuankg when memory allocation requests fail and
0c04407550130c0ea040b5675f2c214426b27718fuankg if the buffers used for sending queries and receiving replies are too
0c04407550130c0ea040b5675f2c214426b27718fuankg<p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>,
0c04407550130c0ea040b5675f2c214426b27718fuankg <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>.