d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<a name="id-1"></a><div class="titlepage"></div>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_create,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_destroy,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_nextserial,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_initserial,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_freemem,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_allocmem,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User lwres_context_sendrecv
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User — lightweight resolver context management
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_create</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t **<var class="pdparam">contextp</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>void *<var class="pdparam">arg</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_malloc_t <var class="pdparam">malloc_function</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_free_t <var class="pdparam">free_function</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_destroy</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t **<var class="pdparam">contextp</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_initserial</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_uint32_t <var class="pdparam">serial</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_uint32_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_nextserial</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_freemem</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>void *<var class="pdparam">mem</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_allocmem</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>void *<var class="pdparam">sendbase</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int <var class="pdparam">sendlen</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>void *<var class="pdparam">recvbase</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int <var class="pdparam">recvlen</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>int *<var class="pdparam">recvd_len</var><code>)</code>;</td>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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 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
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_conf_init</span>(3)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and returned via <em class="parameter"><code>*contextp</code></em>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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>.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <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.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <span class="refentrytitle">lwres_conf_init</span>(3)