/contrib/bind9/lib/lwres/man/lwres_resutil.html
HTML | 258 lines | 240 code | 1 blank | 17 comment | 0 complexity | 59fbf9d45aa92c722f61cc1607a54cb6 MD5 | raw file
1<!-- 2 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 3 - Copyright (C) 2000, 2001 Internet Software Consortium. 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17<!-- $Id$ --> 18<html> 19<head> 20<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 21<title>lwres_resutil</title> 22<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> 23</head> 24<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> 25<a name="id2476275"></a><div class="titlepage"></div> 26<div class="refnamediv"> 27<h2>Name</h2> 28<p>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions</p> 29</div> 30<div class="refsynopsisdiv"> 31<h2>Synopsis</h2> 32<div class="funcsynopsis"> 33<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre> 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 35<tr> 36<td><code class="funcdef"> 37lwres_result_t 38<b class="fsfunc">lwres_string_parse</b>(</code></td> 39<td>lwres_buffer_t * </td> 40<td> 41<var class="pdparam">b</var>, </td> 42</tr> 43<tr> 44<td> </td> 45<td>char ** </td> 46<td> 47<var class="pdparam">c</var>, </td> 48</tr> 49<tr> 50<td> </td> 51<td>lwres_uint16_t * </td> 52<td> 53<var class="pdparam">len</var><code>)</code>;</td> 54</tr> 55</table> 56<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 57<tr> 58<td><code class="funcdef"> 59lwres_result_t 60<b class="fsfunc">lwres_addr_parse</b>(</code></td> 61<td>lwres_buffer_t * </td> 62<td> 63<var class="pdparam">b</var>, </td> 64</tr> 65<tr> 66<td> </td> 67<td>lwres_addr_t * </td> 68<td> 69<var class="pdparam">addr</var><code>)</code>;</td> 70</tr> 71</table> 72<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> 73<tr> 74<td><code class="funcdef"> 75lwres_result_t 76<b class="fsfunc">lwres_getaddrsbyname</b>(</code></td> 77<td>lwres_context_t * </td> 78<td> 79<var class="pdparam">ctx</var>, </td> 80</tr> 81<tr> 82<td> </td> 83<td>const char * </td> 84<td> 85<var class="pdparam">name</var>, </td> 86</tr> 87<tr> 88<td> </td> 89<td>lwres_uint32_t </td> 90<td> 91<var class="pdparam">addrtypes</var>, </td> 92</tr> 93<tr> 94<td> </td> 95<td>lwres_gabnresponse_t ** </td> 96<td> 97<var class="pdparam">structp</var><code>)</code>;</td> 98</tr> 99</table> 100<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> 101<tr> 102<td><code class="funcdef"> 103lwres_result_t 104<b class="fsfunc">lwres_getnamebyaddr</b>(</code></td> 105<td>lwres_context_t * </td> 106<td> 107<var class="pdparam">ctx</var>, </td> 108</tr> 109<tr> 110<td> </td> 111<td>lwres_uint32_t </td> 112<td> 113<var class="pdparam">addrtype</var>, </td> 114</tr> 115<tr> 116<td> </td> 117<td>lwres_uint16_t </td> 118<td> 119<var class="pdparam">addrlen</var>, </td> 120</tr> 121<tr> 122<td> </td> 123<td>const unsigned char * </td> 124<td> 125<var class="pdparam">addr</var>, </td> 126</tr> 127<tr> 128<td> </td> 129<td>lwres_gnbaresponse_t ** </td> 130<td> 131<var class="pdparam">structp</var><code>)</code>;</td> 132</tr> 133</table> 134</div> 135</div> 136<div class="refsect1" lang="en"> 137<a name="id2543470"></a><h2>DESCRIPTION</h2> 138<p><code class="function">lwres_string_parse()</code> 139 retrieves a DNS-encoded string starting the current pointer of 140 lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e. 141 <code class="constant">b->current</code>. When the function returns, 142 the address of the first byte of the encoded string is returned 143 via <em class="parameter"><code>*c</code></em> and the length of that string is 144 given by <em class="parameter"><code>*len</code></em>. The buffer's current 145 pointer is advanced to point at the character following the 146 string length, the encoded string, and the trailing 147 <span class="type">NULL</span> character. 148 </p> 149<p><code class="function">lwres_addr_parse()</code> 150 extracts an address from the buffer <em class="parameter"><code>b</code></em>. 151 The buffer's current pointer <code class="constant">b->current</code> 152 is presumed to point at an encoded address: the address preceded 153 by a 32-bit protocol family identifier and a 16-bit length 154 field. The encoded address is copied to 155 <code class="constant">addr->address</code> and 156 <code class="constant">addr->length</code> indicates the size in bytes 157 of the address that was copied. 158 <code class="constant">b->current</code> is advanced to point at the 159 next byte of available data in the buffer following the encoded 160 address. 161 </p> 162<p><code class="function">lwres_getaddrsbyname()</code> 163 and <code class="function">lwres_getnamebyaddr()</code> use the 164 <span class="type">lwres_gnbaresponse_t</span> structure defined below: 165 </p> 166<pre class="programlisting"> 167typedef struct { 168 lwres_uint32_t flags; 169 lwres_uint16_t naliases; 170 lwres_uint16_t naddrs; 171 char *realname; 172 char **aliases; 173 lwres_uint16_t realnamelen; 174 lwres_uint16_t *aliaslen; 175 lwres_addrlist_t addrs; 176 void *base; 177 size_t baselen; 178} lwres_gabnresponse_t; 179</pre> 180<p> 181 The contents of this structure are not manipulated directly but 182 they are controlled through the 183 <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span> 184 functions. 185 </p> 186<p> 187 The lightweight resolver uses 188 <code class="function">lwres_getaddrsbyname()</code> to perform 189 foward lookups. 190 Hostname <em class="parameter"><code>name</code></em> is looked up using the 191 resolver 192 context <em class="parameter"><code>ctx</code></em> for memory allocation. 193 <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating 194 which type of 195 addresses are to be looked up. Current values for this bitmask are 196 <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and 197 <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the 198 lookup are returned in <em class="parameter"><code>*structp</code></em>. 199 </p> 200<p><code class="function">lwres_getnamebyaddr()</code> 201 performs reverse lookups. Resolver context 202 <em class="parameter"><code>ctx</code></em> is used for memory allocation. The 203 address type is indicated by <em class="parameter"><code>addrtype</code></em>: 204 <span class="type">LWRES_ADDRTYPE_V4</span> or 205 <span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is 206 given by <em class="parameter"><code>addr</code></em> and its length is 207 <em class="parameter"><code>addrlen</code></em> bytes. The result of the 208 function call is made available through 209 <em class="parameter"><code>*structp</code></em>. 210 </p> 211</div> 212<div class="refsect1" lang="en"> 213<a name="id2543609"></a><h2>RETURN VALUES</h2> 214<p> 215 Successful calls to 216 <code class="function">lwres_string_parse()</code> 217 and 218 <code class="function">lwres_addr_parse()</code> 219 return 220 <span class="errorcode">LWRES_R_SUCCESS.</span> 221 Both functions return 222 <span class="errorcode">LWRES_R_FAILURE</span> 223 if the buffer is corrupt or 224 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 225 if the buffer has less space than expected for the components of the 226 encoded string or address. 227 </p> 228<p><code class="function">lwres_getaddrsbyname()</code> 229 returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it 230 returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname 231 <em class="parameter"><code>name</code></em> could not be found. 232 </p> 233<p><span class="errorcode">LWRES_R_SUCCESS</span> 234 is returned by a successful call to 235 <code class="function">lwres_getnamebyaddr()</code>. 236 </p> 237<p> 238 Both 239 <code class="function">lwres_getaddrsbyname()</code> 240 and 241 <code class="function">lwres_getnamebyaddr()</code> 242 return 243 <span class="errorcode">LWRES_R_NOMEMORY</span> 244 when memory allocation requests fail and 245 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> 246 if the buffers used for sending queries and receiving replies are too 247 small. 248 </p> 249</div> 250<div class="refsect1" lang="en"> 251<a name="id2543681"></a><h2>SEE ALSO</h2> 252<p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>, 253 254 <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>. 255 </p> 256</div> 257</div></body> 258</html>