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

   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  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001, 2003  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: lwres_context.docbook,v 1.11 2007/06/18 23:47:51 tbox Exp $ -->
  22 <refentry>
  23
  24   <refentryinfo>
  25     <date>Jun 30, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>lwres_context</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       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  40     </copyright>
  41     <copyright>
  42       <year>2000</year>
  43       <year>2001</year>
  44       <year>2003</year>
  45       <holder>Internet Software Consortium.</holder>
  46     </copyright>
  47   </docinfo>
  48
  49   <refnamediv>
  50     <refname>lwres_context_create</refname>
  51     <refname>lwres_context_destroy</refname>
  52     <refname>lwres_context_nextserial</refname>
  53     <refname>lwres_context_initserial</refname>
  54     <refname>lwres_context_freemem</refname>
  55     <refname>lwres_context_allocmem</refname>
  56     <refname>lwres_context_sendrecv</refname>
  57     <refpurpose>lightweight resolver context management</refpurpose>
  58   </refnamediv>
  59   <refsynopsisdiv>
  60     <funcsynopsis>
  61 <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
  62 <funcprototype>
  63         <funcdef>
  64 lwres_result_t
  65 <function>lwres_context_create</function></funcdef>
  66         <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
  67         <paramdef>void *<parameter>arg</parameter></paramdef>
  68         <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
  69         <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
  70         </funcprototype>
  71 <funcprototype>
  72         <funcdef>
  73 lwres_result_t
  74 <function>lwres_context_destroy</function></funcdef>
  75         <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
  76         </funcprototype>
  77 <funcprototype>
  78         <funcdef>
  79 void
  80 <function>lwres_context_initserial</function></funcdef>
  81         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  82         <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
  83         </funcprototype>
  84 <funcprototype>
  85         <funcdef>
  86 lwres_uint32_t
  87 <function>lwres_context_nextserial</function></funcdef>
  88         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  89         </funcprototype>
  90 <funcprototype>
  91         <funcdef>
  92 void
  93 <function>lwres_context_freemem</function></funcdef>
  94         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  95         <paramdef>void *<parameter>mem</parameter></paramdef>
  96         <paramdef>size_t <parameter>len</parameter></paramdef>
  97         </funcprototype>
  98 <funcprototype>
  99         <funcdef>
 100 void
 101 <function>lwres_context_allocmem</function></funcdef>
 102         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 103         <paramdef>size_t <parameter>len</parameter></paramdef>
 104         </funcprototype>
 105 <funcprototype>
 106         <funcdef>
 107 void *
 108 <function>lwres_context_sendrecv</function></funcdef>
 109         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 110         <paramdef>void *<parameter>sendbase</parameter></paramdef>
 111         <paramdef>int <parameter>sendlen</parameter></paramdef>
 112         <paramdef>void *<parameter>recvbase</parameter></paramdef>
 113         <paramdef>int <parameter>recvlen</parameter></paramdef>
 114         <paramdef>int *<parameter>recvd_len</parameter></paramdef>
 115       </funcprototype>
 116 </funcsynopsis>
 117   </refsynopsisdiv>
 118   <refsect1>
 119     <title>DESCRIPTION</title>
 120
 121     <para><function>lwres_context_create()</function>
 122       creates a <type>lwres_context_t</type> structure for use in
 123       lightweight resolver operations.  It holds a socket and other
 124       data needed for communicating with a resolver daemon.  The new
 125       <type>lwres_context_t</type> is returned through
 126       <parameter>contextp</parameter>, a pointer to a
 127       <type>lwres_context_t</type> pointer.  This
 128       <type>lwres_context_t</type> pointer must initially be NULL, and
 129       is modified to point to the newly created
 130       <type>lwres_context_t</type>.
 131     </para>
 132     <para>
 133       When the lightweight resolver needs to perform dynamic memory
 134       allocation, it will call
 135       <parameter>malloc_function</parameter>
 136       to allocate memory and
 137       <parameter>free_function</parameter>
 138       to free it.  If
 139       <parameter>malloc_function</parameter>
 140       and
 141       <parameter>free_function</parameter>
 142       are NULL, memory is allocated using
 143       <citerefentry>
 144         <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
 145       </citerefentry>.
 146       and
 147       <citerefentry>
 148         <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
 149       </citerefentry>.
 150
 151       It is not permitted to have a NULL
 152       <parameter>malloc_function</parameter> and a non-NULL
 153       <parameter>free_function</parameter> or vice versa.
 154       <parameter>arg</parameter> is passed as the first parameter to
 155       the memory allocation functions.  If
 156       <parameter>malloc_function</parameter> and
 157       <parameter>free_function</parameter> are NULL,
 158       <parameter>arg</parameter> is unused and should be passed as
 159       NULL.
 160     </para>
 161
 162     <para>
 163       Once memory for the structure has been allocated,
 164       it is initialized using
 165       <citerefentry>
 166         <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
 167       </citerefentry>
 168       and returned via <parameter>*contextp</parameter>.
 169     </para>
 170
 171     <para><function>lwres_context_destroy()</function>
 172       destroys a <type>lwres_context_t</type>, closing its socket.
 173       <parameter>contextp</parameter> is a pointer to a pointer to the
 174       context that is to be destroyed.  The pointer will be set to
 175       NULL when the context has been destroyed.
 176     </para>
 177
 178     <para>
 179       The context holds a serial number that is used to identify
 180       resolver request packets and associate responses with the
 181       corresponding requests.  This serial number is controlled using
 182       <function>lwres_context_initserial()</function> and
 183       <function>lwres_context_nextserial()</function>.
 184       <function>lwres_context_initserial()</function> sets the serial
 185       number for context <parameter>*ctx</parameter> to
 186       <parameter>serial</parameter>.
 187       <function>lwres_context_nextserial()</function> increments the
 188       serial number and returns the previous value.
 189     </para>
 190
 191     <para>
 192       Memory for a lightweight resolver context is allocated and freed
 193       using <function>lwres_context_allocmem()</function> and
 194       <function>lwres_context_freemem()</function>.  These use
 195       whatever allocations were defined when the context was created
 196       with <function>lwres_context_create()</function>.
 197       <function>lwres_context_allocmem()</function> allocates
 198       <parameter>len</parameter> bytes of memory and if successful
 199       returns a pointer to the allocated storage.
 200       <function>lwres_context_freemem()</function> frees
 201       <parameter>len</parameter> bytes of space starting at location
 202       <parameter>mem</parameter>.
 203     </para>
 204
 205     <para><function>lwres_context_sendrecv()</function>
 206       performs I/O for the context <parameter>ctx</parameter>.  Data
 207       are read and written from the context's socket.  It writes data
 208       from <parameter>sendbase</parameter> &mdash; typically a
 209       lightweight resolver query packet &mdash; and waits for a reply
 210       which is copied to the receive buffer at
 211       <parameter>recvbase</parameter>.  The number of bytes that were
 212       written to this receive buffer is returned in
 213       <parameter>*recvd_len</parameter>.
 214     </para>
 215   </refsect1>
 216
 217   <refsect1>
 218     <title>RETURN VALUES</title>
 219
 220     <para><function>lwres_context_create()</function>
 221       returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
 222       the <type>struct lwres_context</type> could not be allocated,
 223       <errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
 224     </para>
 225     <para>
 226       Successful calls to the memory allocator
 227       <function>lwres_context_allocmem()</function>
 228       return a pointer to the start of the allocated space.
 229       It returns NULL if memory could not be allocated.
 230     </para>
 231     <para><errorcode>LWRES_R_SUCCESS</errorcode>
 232       is returned when
 233       <function>lwres_context_sendrecv()</function>
 234       completes successfully.
 235       <errorcode>LWRES_R_IOERROR</errorcode>
 236       is returned if an I/O error occurs and
 237       <errorcode>LWRES_R_TIMEOUT</errorcode>
 238       is returned if
 239       <function>lwres_context_sendrecv()</function>
 240       times out waiting for a response.
 241     </para>
 242   </refsect1>
 243   <refsect1>
 244     <title>SEE ALSO</title>
 245     <para><citerefentry>
 246         <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
 247       </citerefentry>,
 248
 249       <citerefentry>
 250         <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
 251       </citerefentry>,
 252
 253       <citerefentry>
 254         <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
 255       </citerefentry>.
 256     </para>
 257   </refsect1>
 258 </refentry><!--
 259  - Local variables:
 260  - mode: sgml
 261  - End:
 262 -->