lwres_context.docbook revision 938440694b33cd752e9e4b71a526368b4811c177
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5cd4555ad444fd391002ae32450572054369fd42Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
938440694b33cd752e9e4b71a526368b4811c177Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or 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.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver context management</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_create</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>arg</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_destroy</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_initserial</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_nextserial</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_freemem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>mem</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>size_t <parameter>len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_allocmem</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>size_t <parameter>len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_context_sendrecv</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>sendbase</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int <parameter>sendlen</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>void *<parameter>recvbase</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int <parameter>recvlen</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>int *<parameter>recvd_len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_context_create()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein creates a <type>lwres_context_t</type> structure for use in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver operations. It holds a socket and other
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein data needed for communicating with a resolver daemon. The new
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_context_t</type> is returned through
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_context_t</type> pointer must initially be NULL, and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is modified to point to the newly created
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein When the lightweight resolver needs to perform dynamic memory
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocation, it will call
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to allocate memory and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to free it. If
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein are NULL, memory is allocated using
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It is not permitted to have a NULL
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>malloc_function</parameter> and a non-NULL
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>free_function</parameter> or vice versa.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>arg</parameter> is passed as the first parameter to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the memory allocation functions. If
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>arg</parameter> is unused and should be passed as
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Once memory for the structure has been allocated,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein it is initialized using
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and returned via <parameter>*contextp</parameter>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_context_destroy()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein destroys a <type>lwres_context_t</type>, closing its socket.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>contextp</parameter> is a pointer to a pointer to the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein context that is to be destroyed. The pointer will be set to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein NULL when the context has been destroyed.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The context holds a serial number that is used to identify
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein resolver request packets and associate responses with the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein corresponding requests. This serial number is controlled using
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_initserial()</function> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_nextserial()</function>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_initserial()</function> sets the serial
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein number for context <parameter>*ctx</parameter> to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_nextserial()</function> increments the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein serial number and returns the previous value.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Memory for a lightweight resolver context is allocated and freed
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein using <function>lwres_context_allocmem()</function> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_freemem()</function>. These use
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein whatever allocations were defined when the context was created
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein with <function>lwres_context_create()</function>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_allocmem()</function> allocates
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>len</parameter> bytes of memory and if successful
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns a pointer to the allocated storage.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_context_freemem()</function> frees
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>len</parameter> bytes of space starting at location
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_context_sendrecv()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein performs I/O for the context <parameter>ctx</parameter>. Data
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein are read and written from the context's socket. It writes data
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein from <parameter>sendbase</parameter> — typically a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver query packet — and waits for a reply
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which is copied to the receive buffer at
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>recvbase</parameter>. The number of bytes that were
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein written to this receive buffer is returned in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_context_create()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the <type>struct lwres_context</type> could not be allocated,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Successful calls to the memory allocator
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return a pointer to the start of the allocated space.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It returns NULL if memory could not be allocated.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned when
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein completes successfully.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned if an I/O error occurs and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned if
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein times out waiting for a response.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml