14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!ENTITY mdash "—">]>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
83a28ca274521e15086fc39febde507bcc4e145eMark Andrews<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
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>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
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
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
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.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
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>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>