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