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