diff options
Diffstat (limited to 'lib/lwres/man/lwres_resutil.html')
| -rw-r--r-- | lib/lwres/man/lwres_resutil.html | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_resutil.html b/lib/lwres/man/lwres_resutil.html new file mode 100644 index 0000000..7bc3e6e --- /dev/null +++ b/lib/lwres/man/lwres_resutil.html @@ -0,0 +1,258 @@ +<!-- + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2000, 2001 Internet Software Consortium. + - + - Permission to use, copy, modify, and distribute this software for any + - purpose with or without fee is hereby granted, provided that the above + - copyright notice and this permission notice appear in all copies. + - + - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, + - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM + - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE + - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + - PERFORMANCE OF THIS SOFTWARE. +--> +<!-- $Id: lwres_resutil.html,v 1.25 2007/01/30 00:24:59 marka Exp $ --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>lwres_resutil</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> +<a name="id2476275"></a><div class="titlepage"></div> +<div class="refnamediv"> +<h2>Name</h2> +<p>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions</p> +</div> +<div class="refsynopsisdiv"> +<h2>Synopsis</h2> +<div class="funcsynopsis"> +<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> +<tr> +<td><code class="funcdef"> +lwres_result_t +<b class="fsfunc">lwres_string_parse</b>(</code></td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> +</tr> +<tr> +<td> </td> +<td>char ** </td> +<td> +<var class="pdparam">c</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_uint16_t * </td> +<td> +<var class="pdparam">len</var><code>)</code>;</td> +</tr> +</table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> +<tr> +<td><code class="funcdef"> +lwres_result_t +<b class="fsfunc">lwres_addr_parse</b>(</code></td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_addr_t * </td> +<td> +<var class="pdparam">addr</var><code>)</code>;</td> +</tr> +</table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> +<tr> +<td><code class="funcdef"> +lwres_result_t +<b class="fsfunc">lwres_getaddrsbyname</b>(</code></td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> +</tr> +<tr> +<td> </td> +<td>const char * </td> +<td> +<var class="pdparam">name</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_uint32_t </td> +<td> +<var class="pdparam">addrtypes</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_gabnresponse_t ** </td> +<td> +<var class="pdparam">structp</var><code>)</code>;</td> +</tr> +</table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> +<tr> +<td><code class="funcdef"> +lwres_result_t +<b class="fsfunc">lwres_getnamebyaddr</b>(</code></td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_uint32_t </td> +<td> +<var class="pdparam">addrtype</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_uint16_t </td> +<td> +<var class="pdparam">addrlen</var>, </td> +</tr> +<tr> +<td> </td> +<td>const unsigned char * </td> +<td> +<var class="pdparam">addr</var>, </td> +</tr> +<tr> +<td> </td> +<td>lwres_gnbaresponse_t ** </td> +<td> +<var class="pdparam">structp</var><code>)</code>;</td> +</tr> +</table> +</div> +</div> +<div class="refsect1" lang="en"> +<a name="id2543466"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_string_parse()</code> + retrieves a DNS-encoded string starting the current pointer of + lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e. + <code class="constant">b->current</code>. When the function returns, + the address of the first byte of the encoded string is returned + via <em class="parameter"><code>*c</code></em> and the length of that string is + given by <em class="parameter"><code>*len</code></em>. The buffer's current + pointer is advanced to point at the character following the + string length, the encoded string, and the trailing + <span class="type">NULL</span> character. + </p> +<p><code class="function">lwres_addr_parse()</code> + extracts an address from the buffer <em class="parameter"><code>b</code></em>. + The buffer's current pointer <code class="constant">b->current</code> + is presumed to point at an encoded address: the address preceded + by a 32-bit protocol family identifier and a 16-bit length + field. The encoded address is copied to + <code class="constant">addr->address</code> and + <code class="constant">addr->length</code> indicates the size in bytes + of the address that was copied. + <code class="constant">b->current</code> is advanced to point at the + next byte of available data in the buffer following the encoded + address. + </p> +<p><code class="function">lwres_getaddrsbyname()</code> + and <code class="function">lwres_getnamebyaddr()</code> use the + <span class="type">lwres_gnbaresponse_t</span> structure defined below: + </p> +<pre class="programlisting"> +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +</pre> +<p> + The contents of this structure are not manipulated directly but + they are controlled through the + <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span> + functions. + </p> +<p> + The lightweight resolver uses + <code class="function">lwres_getaddrsbyname()</code> to perform + foward lookups. + Hostname <em class="parameter"><code>name</code></em> is looked up using the + resolver + context <em class="parameter"><code>ctx</code></em> for memory allocation. + <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating + which type of + addresses are to be looked up. Current values for this bitmask are + <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and + <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the + lookup are returned in <em class="parameter"><code>*structp</code></em>. + </p> +<p><code class="function">lwres_getnamebyaddr()</code> + performs reverse lookups. Resolver context + <em class="parameter"><code>ctx</code></em> is used for memory allocation. The + address type is indicated by <em class="parameter"><code>addrtype</code></em>: + <span class="type">LWRES_ADDRTYPE_V4</span> or + <span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is + given by <em class="parameter"><code>addr</code></em> and its length is + <em class="parameter"><code>addrlen</code></em> bytes. The result of the + function call is made available through + <em class="parameter"><code>*structp</code></em>. + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2543605"></a><h2>RETURN VALUES</h2> +<p> + Successful calls to + <code class="function">lwres_string_parse()</code> + and + <code class="function">lwres_addr_parse()</code> + return + <span class="errorcode">LWRES_R_SUCCESS.</span> + Both functions return + <span class="errorcode">LWRES_R_FAILURE</span> + if the buffer is corrupt or + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffer has less space than expected for the components of the + encoded string or address. + </p> +<p><code class="function">lwres_getaddrsbyname()</code> + returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it + returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname + <em class="parameter"><code>name</code></em> could not be found. + </p> +<p><span class="errorcode">LWRES_R_SUCCESS</span> + is returned by a successful call to + <code class="function">lwres_getnamebyaddr()</code>. + </p> +<p> + Both + <code class="function">lwres_getaddrsbyname()</code> + and + <code class="function">lwres_getnamebyaddr()</code> + return + <span class="errorcode">LWRES_R_NOMEMORY</span> + when memory allocation requests fail and + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffers used for sending queries and receiving replies are too + small. + </p> +</div> +<div class="refsect1" lang="en"> +<a name="id2543676"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>, + + <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>. + </p> +</div> +</div></body> +</html> |