diff options
Diffstat (limited to 'lib/lwres/man/lwres_gabn.html')
| -rw-r--r-- | lib/lwres/man/lwres_gabn.html | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_gabn.html b/lib/lwres/man/lwres_gabn.html new file mode 100644 index 000000000000..fce25c517032 --- /dev/null +++ b/lib/lwres/man/lwres_gabn.html @@ -0,0 +1,357 @@ +<!-- + - Copyright (C) 2004, 2005 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_gabn.html,v 1.6.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>lwres_gabn</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> +<a name="id2482688"></a><div class="titlepage"></div> +<div class="refnamediv"> +<h2>Name</h2> +<p>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling</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_gabnrequest_render</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<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_gabnresponse_render</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<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_gabnrequest_parse</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<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_gabnresponse_parse</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<code>)</code>;</td> +</tr> +</table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> +<tr> +<td><code class="funcdef"> +void +<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<code>)</code>;</td> +</tr> +</table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> +<tr> +<td><code class="funcdef"> +void +<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td>, </td> +</tr> +<tr> +<td> </td> +<td> </td> +<td> +<code>)</code>;</td> +</tr> +</table> +</div> +</div> +<div class="refsect1" lang="en"> +<a name="id2549528"></a><h2>DESCRIPTION</h2> +<p> +These are low-level routines for creating and parsing +lightweight resolver name-to-address lookup request and +response messages. +</p> +<p> +There are four main functions for the getaddrbyname opcode. +One render function converts a getaddrbyname request structure — +<span class="type">lwres_gabnrequest_t</span> — +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a getaddrbyname request structure. +Another render function converts the getaddrbyname response structure — +<span class="type">lwres_gabnresponse_t</span> — +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getaddrbyname response structure. +</p> +<p> +These structures are defined in +<code class="filename"><lwres/lwres.h></code>. +They are shown below. +</p> +<pre class="programlisting"> +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U + +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint32_t addrtypes; + lwres_uint16_t namelen; + char *name; +} lwres_gabnrequest_t; + +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> +</p> +<p> +<code class="function">lwres_gabnrequest_render()</code> +uses resolver context +<em class="parameter"><code>ctx</code></em> +to convert getaddrbyname request structure +<em class="parameter"><code>req</code></em> +to canonical format. +The packet header structure +<em class="parameter"><code>pkt</code></em> +is initialised and transferred to +buffer +<em class="parameter"><code>b</code></em>. + +The contents of +<em class="parameter"><code>*req</code></em> +are then appended to the buffer in canonical format. +<code class="function">lwres_gabnresponse_render()</code> +performs the same task, except it converts a getaddrbyname response structure +<span class="type">lwres_gabnresponse_t</span> +to the lightweight resolver's canonical format. +</p> +<p> +<code class="function">lwres_gabnrequest_parse()</code> +uses context +<em class="parameter"><code>ctx</code></em> +to convert the contents of packet +<em class="parameter"><code>pkt</code></em> +to a +<span class="type">lwres_gabnrequest_t</span> +structure. +Buffer +<em class="parameter"><code>b</code></em> +provides space to be used for storing this structure. +When the function succeeds, the resulting +<span class="type">lwres_gabnrequest_t</span> +is made available through +<em class="parameter"><code>*structp</code></em>. + +<code class="function">lwres_gabnresponse_parse()</code> +offers the same semantics as +<code class="function">lwres_gabnrequest_parse()</code> +except it yields a +<span class="type">lwres_gabnresponse_t</span> +structure. +</p> +<p> +<code class="function">lwres_gabnresponse_free()</code> +and +<code class="function">lwres_gabnrequest_free()</code> +release the memory in resolver context +<em class="parameter"><code>ctx</code></em> +that was allocated to the +<span class="type">lwres_gabnresponse_t</span> +or +<span class="type">lwres_gabnrequest_t</span> +structures referenced via +<em class="parameter"><code>structp</code></em>. + +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +</p> +</div> +<div class="refsect1" lang="en"> +<a name="id2549720"></a><h2>RETURN VALUES</h2> +<p> +The getaddrbyname opcode functions +<code class="function">lwres_gabnrequest_render()</code>, +<code class="function">lwres_gabnresponse_render()</code> +<code class="function">lwres_gabnrequest_parse()</code> +and +<code class="function">lwres_gabnresponse_parse()</code> +all return +<span class="errorcode">LWRES_R_SUCCESS</span> +on success. +They return +<span class="errorcode">LWRES_R_NOMEMORY</span> +if memory allocation fails. +<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> +is returned if the available space in the buffer +<em class="parameter"><code>b</code></em> +is too small to accommodate the packet header or the +<span class="type">lwres_gabnrequest_t</span> +and +<span class="type">lwres_gabnresponse_t</span> +structures. +<code class="function">lwres_gabnrequest_parse()</code> +and +<code class="function">lwres_gabnresponse_parse()</code> +will return +<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> +if the buffer is not empty after decoding the received packet. +These functions will return +<span class="errorcode">LWRES_R_FAILURE</span> +if +<em class="structfield"><code>pktflags</code></em> +in the packet header structure +<span class="type">lwres_lwpacket_t</span> +indicate that the packet is not a response to an earlier query. +</p> +</div> +<div class="refsect1" lang="en"> +<a name="id2549853"></a><h2>SEE ALSO</h2> +<p> +<span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3 +)</span> +</p> +</div> +</div></body> +</html> |