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