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