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