lwres_context.html revision 4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
67a04a3de424d4431f7f41e3a8d025007d2faea4Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
5bf504f5534eab29c9e52f6e8b75c73b3901743fMark Andrews - Permission to use, copy, modify, and/or distribute this software for any
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - purpose with or without fee is hereby granted, provided that the above
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - copyright notice and this permission notice appear in all copies.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
af5073d03288a53b646ec3b807ac25ced64d7879Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
5bf504f5534eab29c9e52f6e8b75c73b3901743fMark Andrews<!-- $Id: lwres_context.html,v 1.24 2009/07/11 01:12:46 tbox Exp $ -->
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
af5073d03288a53b646ec3b807ac25ced64d7879Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<a name="id2476275"></a><div class="titlepage"></div>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<p>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv — lightweight resolver context management</p>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
af5073d03288a53b646ec3b807ac25ced64d7879Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrewslwres_result_t
5bf504f5534eab29c9e52f6e8b75c73b3901743fMark Andrews<b class="fsfunc">lwres_context_create</b>(</code></td>
9016767f4e15191b7c763b8a4ad36a57dc2705a2Mark Andrews<var class="pdparam">malloc_function</var>, </td>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<var class="pdparam">free_function</var><code>)</code>;</td>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrewslwres_result_t
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews<b class="fsfunc">lwres_context_destroy</b>(</code></td>
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews<var class="pdparam">contextp</var><code>)</code>;</td>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<b class="fsfunc">lwres_context_initserial</b>(</code></td>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<var class="pdparam">serial</var><code>)</code>;</td>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrewslwres_uint32_t
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<b class="fsfunc">lwres_context_nextserial</b>(</code></td>
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<var class="pdparam">ctx</var><code>)</code>;</td>
17453368fa0136f6287c56d6600bee58809334bcAndreas Gustafsson<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<b class="fsfunc">lwres_context_freemem</b>(</code></td>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<var class="pdparam">len</var><code>)</code>;</td>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
5bf504f5534eab29c9e52f6e8b75c73b3901743fMark Andrews<b class="fsfunc">lwres_context_allocmem</b>(</code></td>
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews<var class="pdparam">len</var><code>)</code>;</td>
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews<b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson<var class="pdparam">recvd_len</var><code>)</code>;</td>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p><code class="function">lwres_context_create()</code>
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews creates a <span class="type">lwres_context_t</span> structure for use in
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington lightweight resolver operations. It holds a socket and other
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews data needed for communicating with a resolver daemon. The new
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington <span class="type">lwres_context_t</span> is returned through
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews <em class="parameter"><code>contextp</code></em>, a pointer to a
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson <span class="type">lwres_context_t</span> pointer. This
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson <span class="type">lwres_context_t</span> pointer must initially be NULL, and
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson is modified to point to the newly created
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson When the lightweight resolver needs to perform dynamic memory
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson allocation, it will call
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson <em class="parameter"><code>malloc_function</code></em>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson to allocate memory and
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <em class="parameter"><code>free_function</code></em>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews to free it. If
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>malloc_function</code></em>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>free_function</code></em>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews are NULL, memory is allocated using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington It is not permitted to have a NULL
a7038d1a0513c8e804937ebc95fc9cb3a46c04f5Mark Andrews <em class="parameter"><code>malloc_function</code></em> and a non-NULL
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>free_function</code></em> or vice versa.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>arg</code></em> is passed as the first parameter to
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews the memory allocation functions. If
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>malloc_function</code></em> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>free_function</code></em> are NULL,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>arg</code></em> is unused and should be passed as
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Once memory for the structure has been allocated,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington it is initialized using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington and returned via <em class="parameter"><code>*contextp</code></em>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p><code class="function">lwres_context_destroy()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington destroys a <span class="type">lwres_context_t</span>, closing its socket.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington context that is to be destroyed. The pointer will be set to
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington NULL when the context has been destroyed.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The context holds a serial number that is used to identify
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington resolver request packets and associate responses with the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington corresponding requests. This serial number is controlled using
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_initserial()</code> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_nextserial()</code>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_initserial()</code> sets the serial
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington number for context <em class="parameter"><code>*ctx</code></em> to
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>serial</code></em>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_nextserial()</code> increments the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington serial number and returns the previous value.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Memory for a lightweight resolver context is allocated and freed
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington using <code class="function">lwres_context_allocmem()</code> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_freemem()</code>. These use
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington whatever allocations were defined when the context was created
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington with <code class="function">lwres_context_create()</code>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_allocmem()</code> allocates
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>len</code></em> bytes of memory and if successful
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington returns a pointer to the allocated storage.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_freemem()</code> frees
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>len</code></em> bytes of space starting at location
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>mem</code></em>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p><code class="function">lwres_context_sendrecv()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington performs I/O for the context <em class="parameter"><code>ctx</code></em>. Data
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington are read and written from the context's socket. It writes data
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington from <em class="parameter"><code>sendbase</code></em> — typically a
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington lightweight resolver query packet — and waits for a reply
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington which is copied to the receive buffer at
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>recvbase</code></em>. The number of bytes that were
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington written to this receive buffer is returned in
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews <em class="parameter"><code>*recvd_len</code></em>.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington<a name="id2543719"></a><h2>RETURN VALUES</h2>
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington<p><code class="function">lwres_context_create()</code>
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington the <span class="type">struct lwres_context</span> could not be allocated,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington Successful calls to the memory allocator
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington <code class="function">lwres_context_allocmem()</code>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews return a pointer to the start of the allocated space.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington It returns NULL if memory could not be allocated.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p><span class="errorcode">LWRES_R_SUCCESS</span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington is returned when
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_context_sendrecv()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington completes successfully.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="errorcode">LWRES_R_IOERROR</span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington is returned if an I/O error occurs and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="errorcode">LWRES_R_TIMEOUT</span>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington is returned if
4f087942583014b241adca1bc78c6db89ed96e94Mark Andrews <code class="function">lwres_context_sendrecv()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington times out waiting for a response.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.