PageRenderTime 13ms CodeModel.GetById 8ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 1ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 263 lines | 247 code | 16 blank | 0 comment | 0 complexity | 170b2ff398e9d82d9cc71c657de631ed MD5 | raw file
  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>
 65lwres_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>
 74lwres_result_t
 75<function>lwres_context_destroy</function></funcdef>
 76        <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
 77        </funcprototype>
 78<funcprototype>
 79        <funcdef>
 80void
 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>
 87lwres_uint32_t
 88<function>lwres_context_nextserial</function></funcdef>
 89        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 90        </funcprototype>
 91<funcprototype>
 92        <funcdef>
 93void
 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>
101void
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>
108void *
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-->