PageRenderTime 128ms CodeModel.GetById 114ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/bind9/lib/lwres/man/lwres_resutil.docbook

https://bitbucket.org/freebsd/freebsd-head/
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 "&#8212;">]>
  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 &lt;lwres/lwres.h&gt;</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-&gt;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-&gt;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-&gt;address</constant> and
118      <constant>addr-&gt;length</constant> indicates the size in bytes
119      of the address that was copied.
120      <constant>b-&gt;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-->