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