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

   1 <!DOCTYPE book [
   2 <!ENTITY mdash "&#8212;">]>
   3 <!--
   4  - Copyright (C) 2004, 2005, 2007, 2014, 2015  Internet Systems Consortium, Inc. ("ISC")
   5  - Copyright (C) 2000, 2001  Internet Software Consortium.
   6  -
   7  - Permission to use, copy, modify, and/or distribute this software for any
   8  - purpose with or without fee is hereby granted, provided that the above
   9  - copyright notice and this permission notice appear in all copies.
  10  -
  11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  - PERFORMANCE OF THIS SOFTWARE.
  18 -->
  19
  20 <!-- Converted by db4-upgrade version 1.0 -->
  21 <refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
  22   <info>
  23     <date>2007-06-18</date>
  24   </info>
  25   <refentryinfo>
  26     <corpname>ISC</corpname>
  27     <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
  28   </refentryinfo>
  29
  30   <refmeta>
  31     <refentrytitle>lwres_gnba</refentrytitle>
  32     <manvolnum>3</manvolnum>
  33     <refmiscinfo>BIND9</refmiscinfo>
  34   </refmeta>
  35
  36   <docinfo>
  37     <copyright>
  38       <year>2004</year>
  39       <year>2005</year>
  40       <year>2007</year>
  41       <year>2014</year>
  42       <year>2015</year>
  43       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  44     </copyright>
  45     <copyright>
  46       <year>2000</year>
  47       <year>2001</year>
  48       <holder>Internet Software Consortium.</holder>
  49     </copyright>
  50   </docinfo>
  51
  52   <refnamediv>
  53     <refname>lwres_gnbarequest_render</refname>
  54     <refname>lwres_gnbaresponse_render</refname>
  55     <refname>lwres_gnbarequest_parse</refname>
  56     <refname>lwres_gnbaresponse_parse</refname>
  57     <refname>lwres_gnbaresponse_free</refname>
  58     <refname>lwres_gnbarequest_free</refname>
  59     <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
  60   </refnamediv>
  61
  62   <refsynopsisdiv>
  63
  64     <funcsynopsis>
  65 <funcsynopsisinfo>
  66 #include &lt;lwres/lwres.h&gt;
  67 </funcsynopsisinfo>
  68
  69 <funcprototype>
  70         <funcdef>
  71 lwres_result_t
  72 <function>lwres_gnbarequest_render</function>
  73 </funcdef>
  74         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  75         <paramdef>lwres_gnbarequest_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
  80 <funcprototype>
  81         <funcdef>
  82 lwres_result_t
  83 <function>lwres_gnbaresponse_render</function>
  84 </funcdef>
  85         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  86         <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>
  87         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  88         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  89         </funcprototype>
  90 <funcprototype>
  91         <funcdef>
  92 lwres_result_t
  93 <function>lwres_gnbarequest_parse</function></funcdef>
  94         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  95         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  96         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  97         <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
  98         </funcprototype>
  99 <funcprototype>
 100         <funcdef>
 101 lwres_result_t
 102 <function>lwres_gnbaresponse_parse</function></funcdef>
 103         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 104         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 105         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 106         <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
 107         </funcprototype>
 108
 109 <funcprototype>
 110         <funcdef>
 111 void
 112 <function>lwres_gnbaresponse_free</function>
 113 </funcdef>
 114         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 115         <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
 116         </funcprototype>
 117 <funcprototype>
 118         <funcdef>
 119 void
 120 <function>lwres_gnbarequest_free</function></funcdef>
 121         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 122         <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
 123       </funcprototype>
 124 </funcsynopsis>
 125
 126   </refsynopsisdiv>
 127
 128   <refsection><info><title>DESCRIPTION</title></info>
 129
 130     <para>
 131       These are low-level routines for creating and parsing
 132       lightweight resolver address-to-name lookup request and
 133       response messages.
 134     </para>
 135     <para>
 136       There are four main functions for the getnamebyaddr opcode.
 137       One render function converts a getnamebyaddr request structure &mdash;
 138       <type>lwres_gnbarequest_t</type> &mdash;
 139       to the lightweight resolver's canonical format.
 140       It is complemented by a parse function that converts a packet in this
 141       canonical format to a getnamebyaddr request structure.
 142       Another render function converts the getnamebyaddr response structure
 143       &mdash;
 144       <type>lwres_gnbaresponse_t</type>
 145       to the canonical format.
 146       This is complemented by a parse function which converts a packet in
 147       canonical format to a getnamebyaddr response structure.
 148     </para>
 149     <para>
 150       These structures are defined in
 151       <filename>lwres/lwres.h</filename>.
 152       They are shown below.
 153     </para>
 154     <para><programlisting>
 155 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 156 </programlisting>
 157     </para>
 158     <para><programlisting>
 159 typedef struct {
 160         lwres_uint32_t  flags;
 161         lwres_addr_t    addr;
 162 } lwres_gnbarequest_t;
 163 </programlisting>
 164     </para>
 165     <para><programlisting>
 166 typedef struct {
 167         lwres_uint32_t  flags;
 168         lwres_uint16_t  naliases;
 169         char           *realname;
 170         char          **aliases;
 171         lwres_uint16_t  realnamelen;
 172         lwres_uint16_t *aliaslen;
 173         void           *base;
 174         size_t          baselen;
 175 } lwres_gnbaresponse_t;
 176 </programlisting>
 177     </para>
 178
 179     <para><function>lwres_gnbarequest_render()</function>
 180       uses resolver context <varname>ctx</varname> to convert
 181       getnamebyaddr request structure <varname>req</varname> to
 182       canonical format.  The packet header structure
 183       <varname>pkt</varname> is initialised and transferred to buffer
 184       <varname>b</varname>.  The contents of <varname>*req</varname>
 185       are then appended to the buffer in canonical format.
 186       <function>lwres_gnbaresponse_render()</function> performs the
 187       same task, except it converts a getnamebyaddr response structure
 188       <type>lwres_gnbaresponse_t</type> to the lightweight resolver's
 189       canonical format.
 190     </para>
 191
 192     <para><function>lwres_gnbarequest_parse()</function>
 193       uses context <varname>ctx</varname> to convert the contents of
 194       packet <varname>pkt</varname> to a
 195       <type>lwres_gnbarequest_t</type> structure.  Buffer
 196       <varname>b</varname> provides space to be used for storing this
 197       structure.  When the function succeeds, the resulting
 198       <type>lwres_gnbarequest_t</type> is made available through
 199       <varname>*structp</varname>.
 200       <function>lwres_gnbaresponse_parse()</function> offers the same
 201       semantics as <function>lwres_gnbarequest_parse()</function>
 202       except it yields a <type>lwres_gnbaresponse_t</type> structure.
 203     </para>
 204
 205     <para><function>lwres_gnbaresponse_free()</function>
 206       and <function>lwres_gnbarequest_free()</function> release the
 207       memory in resolver context <varname>ctx</varname> that was
 208       allocated to the <type>lwres_gnbaresponse_t</type> or
 209       <type>lwres_gnbarequest_t</type> structures referenced via
 210       <varname>structp</varname>.  Any memory associated with
 211       ancillary buffers and strings for those structures is also
 212       discarded.
 213     </para>
 214   </refsection>
 215
 216   <refsection><info><title>RETURN VALUES</title></info>
 217
 218     <para>
 219       The getnamebyaddr opcode functions
 220       <function>lwres_gnbarequest_render()</function>,
 221       <function>lwres_gnbaresponse_render()</function>
 222       <function>lwres_gnbarequest_parse()</function>
 223       and
 224       <function>lwres_gnbaresponse_parse()</function>
 225       all return
 226       <errorcode>LWRES_R_SUCCESS</errorcode>
 227       on success.
 228       They return
 229       <errorcode>LWRES_R_NOMEMORY</errorcode>
 230       if memory allocation fails.
 231       <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 232       is returned if the available space in the buffer
 233       <varname>b</varname>
 234       is too small to accommodate the packet header or the
 235       <type>lwres_gnbarequest_t</type>
 236       and
 237       <type>lwres_gnbaresponse_t</type>
 238       structures.
 239       <function>lwres_gnbarequest_parse()</function>
 240       and
 241       <function>lwres_gnbaresponse_parse()</function>
 242       will return
 243       <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 244       if the buffer is not empty after decoding the received packet.
 245       These functions will return
 246       <errorcode>LWRES_R_FAILURE</errorcode>
 247       if
 248       <varname remap="structfield">pktflags</varname>
 249       in the packet header structure
 250       <type>lwres_lwpacket_t</type>
 251       indicate that the packet is not a response to an earlier query.
 252     </para>
 253   </refsection>
 254   <refsection><info><title>SEE ALSO</title></info>
 255
 256     <para><citerefentry>
 257         <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
 258       </citerefentry>.
 259     </para>
 260   </refsection>
 261 </refentry>