lwres_context.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<!ENTITY mdash "—">]>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - Permission to use, copy, modify, and/or distribute this software for any
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - purpose with or without fee is hereby granted, provided that the above
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - copyright notice and this permission notice appear in all copies.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel - PERFORMANCE OF THIS SOFTWARE.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<!-- Converted by db4-upgrade version 1.0 -->
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentryinfo>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refentryinfo>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </copyright>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </copyright>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refnamediv>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refpurpose>lightweight resolver context management</refpurpose>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refnamediv>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refsynopsisdiv>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <funcsynopsis>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishellwres_result_t
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_create</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>void *<parameter>arg</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishellwres_result_t
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_destroy</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_initserial</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishellwres_uint32_t
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_nextserial</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_freemem</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>void *<parameter>mem</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>size_t <parameter>len</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_allocmem</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>size_t <parameter>len</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel<function>lwres_context_sendrecv</function></funcdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>void *<parameter>sendbase</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>int <parameter>sendlen</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>void *<parameter>recvbase</parameter></paramdef>
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO <paramdef>int <parameter>recvlen</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <paramdef>int *<parameter>recvd_len</parameter></paramdef>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </funcprototype>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel</funcsynopsis>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refsynopsisdiv>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refsection><info><title>DESCRIPTION</title></info>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <para><function>lwres_context_create()</function>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel creates a <type>lwres_context_t</type> structure for use in
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel lightweight resolver operations. It holds a socket and other
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO data needed for communicating with a resolver daemon. The new
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <type>lwres_context_t</type> is returned through
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>contextp</parameter>, a pointer to a
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <type>lwres_context_t</type> pointer must initially be NULL, and
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel is modified to point to the newly created
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel When the lightweight resolver needs to perform dynamic memory
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel allocation, it will call
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel to allocate memory and
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel to free it. If
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel are NULL, memory is allocated using
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <citerefentry>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </citerefentry>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <citerefentry>
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </citerefentry>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel It is not permitted to have a NULL
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>malloc_function</parameter> and a non-NULL
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>free_function</parameter> or vice versa.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>arg</parameter> is passed as the first parameter to
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel the memory allocation functions. If
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>arg</parameter> is unused and should be passed as
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel Once memory for the structure has been allocated,
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel it is initialized using
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <citerefentry>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO </citerefentry>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel and returned via <parameter>*contextp</parameter>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <para><function>lwres_context_destroy()</function>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel destroys a <type>lwres_context_t</type>, closing its socket.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>contextp</parameter> is a pointer to a pointer to the
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel context that is to be destroyed. The pointer will be set to
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel NULL when the context has been destroyed.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel The context holds a serial number that is used to identify
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel resolver request packets and associate responses with the
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel corresponding requests. This serial number is controlled using
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_initserial()</function> and
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_nextserial()</function>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_initserial()</function> sets the serial
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel number for context <parameter>*ctx</parameter> to
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_nextserial()</function> increments the
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel serial number and returns the previous value.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel Memory for a lightweight resolver context is allocated and freed
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel using <function>lwres_context_allocmem()</function> and
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_freemem()</function>. These use
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel whatever allocations were defined when the context was created
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel with <function>lwres_context_create()</function>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_allocmem()</function> allocates
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>len</parameter> bytes of memory and if successful
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel returns a pointer to the allocated storage.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <function>lwres_context_freemem()</function> frees
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>len</parameter> bytes of space starting at location
90b1de135fcfa7ce4adc9138a885aa94bbcef04fRichard PALO <para><function>lwres_context_sendrecv()</function>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel performs I/O for the context <parameter>ctx</parameter>. Data
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel are read and written from the context's socket. It writes data
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel from <parameter>sendbase</parameter> — typically a
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel lightweight resolver query packet — and waits for a reply
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel which is copied to the receive buffer at
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <parameter>recvbase</parameter>. The number of bytes that were
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel written to this receive buffer is returned in
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refsection>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refsection><info><title>RETURN VALUES</title></info>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <para><function>lwres_context_create()</function>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel the <type>struct lwres_context</type> could not be allocated,
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel Successful calls to the memory allocator
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel return a pointer to the start of the allocated space.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel It returns NULL if memory could not be allocated.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel is returned when
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel completes successfully.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel is returned if an I/O error occurs and
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel is returned if
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel times out waiting for a response.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refsection>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refsection><info><title>SEE ALSO</title></info>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </citerefentry>,
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <citerefentry>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </citerefentry>,
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <citerefentry>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </citerefentry>.
eca2601cae391051acb146d28fba04237fe1eb85Randy Fishel </refsection>