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