PageRenderTime 27ms CodeModel.GetById 22ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 261 lines | 250 code | 11 blank | 0 comment | 0 complexity | 1623587ae5b9113834247e1b40b41ef4 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_gabn</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_gabnrequest_render</refname>
 51    <refname>lwres_gabnresponse_render</refname>
 52    <refname>lwres_gabnrequest_parse</refname>
 53    <refname>lwres_gabnresponse_parse</refname>
 54    <refname>lwres_gabnresponse_free</refname>
 55    <refname>lwres_gabnrequest_free</refname>
 56    <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
 57  </refnamediv>
 58  <refsynopsisdiv>
 59    <funcsynopsis>
 60<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
 61<funcprototype>
 62        <funcdef>
 63lwres_result_t
 64<function>lwres_gabnrequest_render</function></funcdef>
 65        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 66        <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
 67        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 68        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 69        </funcprototype>
 70<funcprototype>
 71        <funcdef>
 72lwres_result_t
 73<function>lwres_gabnresponse_render</function></funcdef>
 74        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 75        <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
 76        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 77        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 78        </funcprototype>
 79<funcprototype>
 80        <funcdef>
 81lwres_result_t
 82<function>lwres_gabnrequest_parse</function></funcdef>
 83        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 84        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 85        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 86        <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
 87        </funcprototype>
 88<funcprototype>
 89        <funcdef>
 90lwres_result_t
 91<function>lwres_gabnresponse_parse</function></funcdef>
 92        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 93        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 94        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 95        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
 96        </funcprototype>
 97<funcprototype>
 98        <funcdef>
 99void
100<function>lwres_gabnresponse_free</function></funcdef>
101        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
102        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
103        </funcprototype>
104<funcprototype>
105        <funcdef>
106void
107<function>lwres_gabnrequest_free</function></funcdef>
108        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
109        <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
110      </funcprototype>
111</funcsynopsis>
112  </refsynopsisdiv>
113  <refsect1>
114    <title>DESCRIPTION</title>
115    <para>
116      These are low-level routines for creating and parsing
117      lightweight resolver name-to-address lookup request and
118      response messages.
119    </para>
120    <para>
121      There are four main functions for the getaddrbyname opcode.
122      One render function converts a getaddrbyname request structure &mdash;
123      <type>lwres_gabnrequest_t</type> &mdash;
124      to the lighweight resolver's canonical format.
125      It is complemented by a parse function that converts a packet in this
126      canonical format to a getaddrbyname request structure.
127      Another render function converts the getaddrbyname response structure
128      &mdash; <type>lwres_gabnresponse_t</type> &mdash;
129      to the canonical format.
130      This is complemented by a parse function which converts a packet in
131      canonical format to a getaddrbyname response structure.
132    </para>
133    <para>
134      These structures are defined in
135      <filename>&lt;lwres/lwres.h&gt;</filename>.
136      They are shown below.
137    </para>
138    <para><programlisting>
139#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
140</programlisting>
141    </para>
142    <para><programlisting>
143typedef struct lwres_addr lwres_addr_t;
144typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
145</programlisting>
146    </para>
147    <para><programlisting>
148typedef struct {
149        lwres_uint32_t  flags;
150        lwres_uint32_t  addrtypes;
151        lwres_uint16_t  namelen;
152        char           *name;
153} lwres_gabnrequest_t;
154</programlisting>
155    </para>
156    <para><programlisting>
157typedef struct {
158        lwres_uint32_t          flags;
159        lwres_uint16_t          naliases;
160        lwres_uint16_t          naddrs;
161        char                   *realname;
162        char                  **aliases;
163        lwres_uint16_t          realnamelen;
164        lwres_uint16_t         *aliaslen;
165        lwres_addrlist_t        addrs;
166        void                   *base;
167        size_t                  baselen;
168} lwres_gabnresponse_t;
169</programlisting>
170    </para>
171
172    <para><function>lwres_gabnrequest_render()</function>
173      uses resolver context <parameter>ctx</parameter> to convert
174      getaddrbyname request structure <parameter>req</parameter> to
175      canonical format.  The packet header structure
176      <parameter>pkt</parameter> is initialised and transferred to
177      buffer <parameter>b</parameter>.
178
179      The contents of <parameter>*req</parameter> are then appended to
180      the buffer in canonical format.
181      <function>lwres_gabnresponse_render()</function> performs the
182      same task, except it converts a getaddrbyname response structure
183      <type>lwres_gabnresponse_t</type> to the lightweight resolver's
184      canonical format.
185    </para>
186
187    <para><function>lwres_gabnrequest_parse()</function>
188      uses context <parameter>ctx</parameter> to convert the contents
189      of packet <parameter>pkt</parameter> to a
190      <type>lwres_gabnrequest_t</type> structure.  Buffer
191      <parameter>b</parameter> provides space to be used for storing
192      this structure.  When the function succeeds, the resulting
193      <type>lwres_gabnrequest_t</type> is made available through
194      <parameter>*structp</parameter>.
195
196      <function>lwres_gabnresponse_parse()</function> offers the same
197      semantics as <function>lwres_gabnrequest_parse()</function>
198      except it yields a <type>lwres_gabnresponse_t</type> structure.
199    </para>
200
201    <para><function>lwres_gabnresponse_free()</function>
202      and <function>lwres_gabnrequest_free()</function> release the
203      memory in resolver context <parameter>ctx</parameter> that was
204      allocated to the <type>lwres_gabnresponse_t</type> or
205      <type>lwres_gabnrequest_t</type> structures referenced via
206      <parameter>structp</parameter>.
207
208      Any memory associated with ancillary buffers and strings for
209      those structures is also discarded.
210    </para>
211  </refsect1>
212  <refsect1>
213    <title>RETURN VALUES</title>
214    <para>
215      The getaddrbyname opcode functions
216      <function>lwres_gabnrequest_render()</function>,
217      <function>lwres_gabnresponse_render()</function>
218      <function>lwres_gabnrequest_parse()</function>
219      and
220      <function>lwres_gabnresponse_parse()</function>
221      all return
222      <errorcode>LWRES_R_SUCCESS</errorcode>
223      on success.
224      They return
225      <errorcode>LWRES_R_NOMEMORY</errorcode>
226      if memory allocation fails.
227      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
228      is returned if the available space in the buffer
229      <parameter>b</parameter>
230      is too small to accommodate the packet header or the
231      <type>lwres_gabnrequest_t</type>
232      and
233      <type>lwres_gabnresponse_t</type>
234      structures.
235      <function>lwres_gabnrequest_parse()</function>
236      and
237      <function>lwres_gabnresponse_parse()</function>
238      will return
239      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
240      if the buffer is not empty after decoding the received packet.
241      These functions will return
242      <errorcode>LWRES_R_FAILURE</errorcode>
243      if
244      <structfield>pktflags</structfield>
245      in the packet header structure
246      <type>lwres_lwpacket_t</type>
247      indicate that the packet is not a response to an earlier query.
248    </para>
249  </refsect1>
250  <refsect1>
251    <title>SEE ALSO</title>
252    <para><citerefentry>
253        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
254      </citerefentry>
255    </para>
256  </refsect1>
257</refentry><!--
258 - Local variables:
259 - mode: sgml
260 - End:
261-->