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

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and 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.3.2.2.2.3 2005/05/12 21:36:12 sra Exp $ -->
  22
  23 <refentry>
  24 <refentryinfo>
  25
  26
  27 <date>Jun 30, 2000</date>
  28 </refentryinfo>
  29 <refmeta>
  30 <refentrytitle>lwres_context</refentrytitle>
  31 <manvolnum>3</manvolnum>
  32 <refmiscinfo>BIND9</refmiscinfo>
  33 </refmeta>
  34
  35   <docinfo>
  36     <copyright>
  37       <year>2004</year>
  38       <year>2005</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 **contextp</paramdef>
  67 <paramdef>void *arg</paramdef>
  68 <paramdef>lwres_malloc_t malloc_function</paramdef>
  69 <paramdef>lwres_free_t free_function</paramdef>
  70 </funcprototype>
  71 <funcprototype>
  72 <funcdef>
  73 lwres_result_t
  74 <function>lwres_context_destroy</function></funcdef>
  75 <paramdef>lwres_context_t **contextp</paramdef>
  76 </funcprototype>
  77 <funcprototype>
  78 <funcdef>
  79 void
  80 <function>lwres_context_initserial</function></funcdef>
  81 <paramdef>lwres_context_t *ctx</paramdef>
  82 <paramdef>lwres_uint32_t serial</paramdef>
  83 </funcprototype>
  84 <funcprototype>
  85 <funcdef>
  86 lwres_uint32_t
  87 <function>lwres_context_nextserial</function></funcdef>
  88 <paramdef>lwres_context_t *ctx</paramdef>
  89 </funcprototype>
  90 <funcprototype>
  91 <funcdef>
  92 void
  93 <function>lwres_context_freemem</function></funcdef>
  94 <paramdef>lwres_context_t *ctx</paramdef>
  95 <paramdef>void *mem</paramdef>
  96 <paramdef>size_t len</paramdef>
  97 </funcprototype>
  98 <funcprototype>
  99 <funcdef>
 100 void
 101 <function>lwres_context_allocmem</function></funcdef>
 102 <paramdef>lwres_context_t *ctx</paramdef>
 103 <paramdef>size_t len</paramdef>
 104 </funcprototype>
 105 <funcprototype>
 106 <funcdef>
 107 void *
 108 <function>lwres_context_sendrecv</function></funcdef>
 109 <paramdef>lwres_context_t *ctx</paramdef>
 110 <paramdef>void *sendbase</paramdef>
 111 <paramdef>int sendlen</paramdef>
 112 <paramdef>void *recvbase</paramdef>
 113 <paramdef>int recvlen</paramdef>
 114 <paramdef>int *recvd_len</paramdef>
 115 </funcprototype>
 116 </funcsynopsis>
 117 </refsynopsisdiv>
 118 <refsect1>
 119 <title>DESCRIPTION</title>
 120 <para>
 121 <function>lwres_context_create()</function>
 122 creates a
 123 <type>lwres_context_t</type>
 124 structure for use in lightweight resolver operations.
 125 It holds a socket and other data needed for communicating
 126 with a resolver daemon.
 127 The new
 128 <type>lwres_context_t</type>
 129 is returned through
 130 <parameter>contextp</parameter>,
 131
 132 a pointer to a
 133 <type>lwres_context_t</type>
 134 pointer.  This
 135 <type>lwres_context_t</type>
 136 pointer must initially be NULL, and is modified
 137 to point to the newly created
 138 <type>lwres_context_t</type>.
 139
 140 </para>
 141 <para>
 142 When the lightweight resolver needs to perform dynamic memory
 143 allocation, it will call
 144 <parameter>malloc_function</parameter>
 145 to allocate memory and
 146 <parameter>free_function</parameter>
 147
 148 to free it.  If
 149 <parameter>malloc_function</parameter>
 150 and
 151 <parameter>free_function</parameter>
 152
 153 are NULL, memory is allocated using
 154 .Xr malloc 3
 155 and
 156 <citerefentry>
 157 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
 158 </citerefentry>.
 159
 160 It is not permitted to have a NULL
 161 <parameter>malloc_function</parameter>
 162 and a non-NULL
 163 <parameter>free_function</parameter>
 164 or vice versa.
 165 <parameter>arg</parameter>
 166 is passed as the first parameter to the memory
 167 allocation functions.
 168 If
 169 <parameter>malloc_function</parameter>
 170 and
 171 <parameter>free_function</parameter>
 172 are NULL,
 173 <parameter>arg</parameter>
 174
 175 is unused and should be passed as NULL.
 176 </para>
 177 <para>
 178 Once memory for the structure has been allocated,
 179 it is initialized using
 180 <citerefentry>
 181 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
 182 </citerefentry>
 183
 184 and returned via
 185 <parameter>*contextp</parameter>.
 186
 187 </para>
 188 <para>
 189 <function>lwres_context_destroy()</function>
 190 destroys a
 191 <type>lwres_context_t</type>,
 192
 193 closing its socket.
 194 <parameter>contextp</parameter>
 195 is a pointer to a pointer to the context that is to be destroyed.
 196 The pointer will be set to NULL when the context has been destroyed.
 197 </para>
 198 <para>
 199 The context holds a serial number that is used to identify resolver
 200 request packets and associate responses with the corresponding requests.
 201 This serial number is controlled using
 202 <function>lwres_context_initserial()</function>
 203 and
 204 <function>lwres_context_nextserial()</function>.
 205 <function>lwres_context_initserial()</function>
 206 sets the serial number for context
 207 <parameter>*ctx</parameter>
 208 to
 209 <parameter>serial</parameter>.
 210
 211 <function>lwres_context_nextserial()</function>
 212 increments the serial number and returns the previous value.
 213 </para>
 214 <para>
 215 Memory for a lightweight resolver context is allocated and freed using
 216 <function>lwres_context_allocmem()</function>
 217 and
 218 <function>lwres_context_freemem()</function>.
 219 These use whatever allocations were defined when the context was
 220 created with
 221 <function>lwres_context_create()</function>.
 222 <function>lwres_context_allocmem()</function>
 223 allocates
 224 <parameter>len</parameter>
 225 bytes of memory and if successful returns a pointer to the allocated
 226 storage.
 227 <function>lwres_context_freemem()</function>
 228 frees
 229 <parameter>len</parameter>
 230 bytes of space starting at location
 231 <parameter>mem</parameter>.
 232
 233 </para>
 234 <para>
 235 <function>lwres_context_sendrecv()</function>
 236 performs I/O for the context
 237 <parameter>ctx</parameter>.
 238
 239 Data are read and written from the context's socket.
 240 It writes data from
 241 <parameter>sendbase</parameter>
 242 &mdash; typically a lightweight resolver query packet &mdash;
 243 and waits for a reply which is copied to the receive buffer at
 244 <parameter>recvbase</parameter>.
 245
 246 The number of bytes that were written to this receive buffer is
 247 returned in
 248 <parameter>*recvd_len</parameter>.
 249
 250 </para>
 251 </refsect1>
 252 <refsect1>
 253 <title>RETURN VALUES</title>
 254 <para>
 255 <function>lwres_context_create()</function>
 256 returns
 257 <errorcode>LWRES_R_NOMEMORY</errorcode>
 258 if memory for the
 259 <type>struct lwres_context</type>
 260 could not be allocated,
 261 <errorcode>LWRES_R_SUCCESS</errorcode>
 262 otherwise.
 263 </para>
 264 <para>
 265 Successful calls to the memory allocator
 266 <function>lwres_context_allocmem()</function>
 267 return a pointer to the start of the allocated space.
 268 It returns NULL if memory could not be allocated.
 269 </para>
 270 <para>
 271 <errorcode>LWRES_R_SUCCESS</errorcode>
 272 is returned when
 273 <function>lwres_context_sendrecv()</function>
 274 completes successfully.
 275 <errorcode>LWRES_R_IOERROR</errorcode>
 276 is returned if an I/O error occurs and
 277 <errorcode>LWRES_R_TIMEOUT</errorcode>
 278 is returned if
 279 <function>lwres_context_sendrecv()</function>
 280 times out waiting for a response.
 281 </para>
 282 </refsect1>
 283 <refsect1>
 284 <title>SEE ALSO</title>
 285 <para>
 286 <citerefentry>
 287 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
 288 </citerefentry>,
 289
 290 <citerefentry>
 291 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
 292 </citerefentry>,
 293
 294 <citerefentry>
 295 <refentrytitle>free</refentrytitle><manvolnum>3
 296 </manvolnum>
 297 </citerefentry>.
 298 </para>
 299 </refsect1>
 300 </refentry>