lwres_context.html revision fd2597f75693a2279fdf588bd40dfe2407c42028
0b062f4990db5cc6db2fe3398926f71b92a67407Brian Wellington - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
46bb3884a0738664862e3a36b7848aa374aebd45Tinderbox User - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and/or distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - purpose with or without fee is hereby granted, provided that the above
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - copyright notice and this permission notice appear in all copies.
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - 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,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<a name="id-1"></a><div class="titlepage"></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<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>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlwres_result_t
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<b class="fsfunc">lwres_context_create</b>(</code></td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_context_t **<var class="pdparam">contextp</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>void *<var class="pdparam">arg</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_malloc_t <var class="pdparam">malloc_function</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_free_t <var class="pdparam">free_function</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlwres_result_t
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<b class="fsfunc">lwres_context_destroy</b>(</code></td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_context_t **<var class="pdparam">contextp</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<b class="fsfunc">lwres_context_initserial</b>(</code></td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_uint32_t <var class="pdparam">serial</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrewslwres_uint32_t
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<b class="fsfunc">lwres_context_nextserial</b>(</code></td>
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater<td>lwres_context_t *<var class="pdparam">ctx</var><code>)</code>;</td>
ad671240d635376dd8681550eebee799d2e3d1fdAutomatic Updater<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<b class="fsfunc">lwres_context_freemem</b>(</code></td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>void *<var class="pdparam">mem</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<b class="fsfunc">lwres_context_allocmem</b>(</code></td>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>void *<var class="pdparam">sendbase</var>, </td>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<td>int <var class="pdparam">sendlen</var>, </td>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<td>void *<var class="pdparam">recvbase</var>, </td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<td>int <var class="pdparam">recvlen</var>, </td>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<td>int *<var class="pdparam">recvd_len</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><code class="function">lwres_context_create()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User creates a <span class="type">lwres_context_t</span> structure for use in
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User lightweight resolver operations. It holds a socket and other
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User data needed for communicating with a resolver daemon. The new
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="type">lwres_context_t</span> is returned through
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <em class="parameter"><code>contextp</code></em>, a pointer to a
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="type">lwres_context_t</span> pointer. This
2f8d63983c297c62630044d28a6f66676b4d339dMark Andrews <span class="type">lwres_context_t</span> pointer must initially be NULL, and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User is modified to point to the newly created
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User When the lightweight resolver needs to perform dynamic memory
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater allocation, it will call
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <em class="parameter"><code>malloc_function</code></em>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User to allocate memory and
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <em class="parameter"><code>free_function</code></em>
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User to free it. If
bfb7b680bf88c1fdd9949197b71c512c532280a4Tinderbox User <em class="parameter"><code>malloc_function</code></em>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>free_function</code></em>
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater are NULL, memory is allocated using
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater It is not permitted to have a NULL
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <em class="parameter"><code>malloc_function</code></em> and a non-NULL
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <em class="parameter"><code>free_function</code></em> or vice versa.
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater <em class="parameter"><code>arg</code></em> is passed as the first parameter to
0a7ed88633a680bb881868b75ded4d09a7bbbc50Automatic Updater the memory allocation functions. If
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>malloc_function</code></em> and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User Once memory for the structure has been allocated,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User it is initialized using
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
8ec3c085233cedb22b05da36e2773c8f357a7e45Automatic Updater and returned via <em class="parameter"><code>*contextp</code></em>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><code class="function">lwres_context_destroy()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User destroys a <span class="type">lwres_context_t</span>, closing its socket.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User context that is to be destroyed. The pointer will be set to
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User NULL when the context has been destroyed.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User The context holds a serial number that is used to identify
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User resolver request packets and associate responses with the
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User corresponding requests. This serial number is controlled using
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <code class="function">lwres_context_initserial()</code> and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="function">lwres_context_nextserial()</code>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_context_initserial()</code> sets the serial
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User number for context <em class="parameter"><code>*ctx</code></em> to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>serial</code></em>.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <code class="function">lwres_context_nextserial()</code> increments the
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User serial number and returns the previous value.
f8e3e03cacd16ffb923a9603fca23a9e1a1fee07Automatic Updater Memory for a lightweight resolver context is allocated and freed
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User using <code class="function">lwres_context_allocmem()</code> and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="function">lwres_context_freemem()</code>. These use
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User whatever allocations were defined when the context was created
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User with <code class="function">lwres_context_create()</code>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="function">lwres_context_allocmem()</code> allocates
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>len</code></em> bytes of memory and if successful
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein returns a pointer to the allocated storage.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <code class="function">lwres_context_freemem()</code> frees
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>len</code></em> bytes of space starting at location
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User<p><code class="function">lwres_context_sendrecv()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User performs I/O for the context <em class="parameter"><code>ctx</code></em>. Data
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User are read and written from the context's socket. It writes data
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User from <em class="parameter"><code>sendbase</code></em> — typically a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lightweight resolver query packet — and waits for a reply
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User which is copied to the receive buffer at
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <em class="parameter"><code>recvbase</code></em>. The number of bytes that were
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User written to this receive buffer is returned in
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <em class="parameter"><code>*recvd_len</code></em>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><code class="function">lwres_context_create()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User the <span class="type">struct lwres_context</span> could not be allocated,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Successful calls to the memory allocator
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <code class="function">lwres_context_allocmem()</code>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User return a pointer to the start of the allocated space.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User It returns NULL if memory could not be allocated.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><span class="errorcode">LWRES_R_SUCCESS</span>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User is returned when
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <code class="function">lwres_context_sendrecv()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User completes successfully.
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="errorcode">LWRES_R_IOERROR</span>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User is returned if an I/O error occurs and
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="errorcode">LWRES_R_TIMEOUT</span>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User is returned if
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <code class="function">lwres_context_sendrecv()</code>
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User times out waiting for a response.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
e62b9c9ce6413fb183c8116381e75dcd07ca5517Tinderbox User <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.