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