lwres_context.docbook revision dafcb997e390efa4423883dafd100c975c4095d6
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - Copyright (C) 2001, 2003 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!-- $Id: lwres_context.docbook,v 1.5 2004/03/05 05:12:56 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_context</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_context_nextserial</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_context_initserial</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver context management</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_create</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_context_t **contextp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_malloc_t malloc_function</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_free_t free_function</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_destroy</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_context_t **contextp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_initserial</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint32_t serial</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_nextserial</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_freemem</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_allocmem</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_sendrecv</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_create()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure for use in lightweight resolver operations.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt holds a socket and other data needed for communicating
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwith a resolver daemon.
be8aff07bb6a863c46874021f2ce8304b721632aMark Andrewsis returned through
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonpointer must initially be NULL, and is modified
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto point to the newly created
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the lightweight resolver needs to perform dynamic memory
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonallocation, it will call
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto allocate memory and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonare NULL, memory is allocated using
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt is not permitted to have a NULL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis passed as the first parameter to the memory
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonallocation functions.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis unused and should be passed as NULL.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOnce memory for the structure has been allocated,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonit is initialized using
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand returned via
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_destroy()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonclosing its socket.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a pointer to a pointer to the context that is to be destroyed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe pointer will be set to NULL when the context has been destroyed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe context holds a serial number that is used to identify resolver
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrequest packets and associate responses with the corresponding requests.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis serial number is controlled using
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_initserial()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_nextserial()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_initserial()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonsets the serial number for context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_nextserial()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonincrements the serial number and returns the previous value.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonMemory for a lightweight resolver context is allocated and freed using
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_allocmem()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_freemem()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese use whatever allocations were defined when the context was
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_create()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_allocmem()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes of memory and if successful returns a pointer to the allocated
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_freemem()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes of space starting at location
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_sendrecv()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms I/O for the context
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonData are read and written from the context's socket.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt writes data from
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson— typically a lightweight resolver query packet —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand waits for a reply which is copied to the receive buffer at
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe number of bytes that were written to this receive buffer is
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_create()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif memory for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncould not be allocated,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to the memory allocator
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_allocmem()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturn a pointer to the start of the allocated space.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt returns NULL if memory could not be allocated.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned when
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_sendrecv()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncompletes successfully.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned if an I/O error occurs and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_sendrecv()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontimes out waiting for a response.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>free</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.