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