1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3 [<!ENTITY mdash "—">]>
5 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
8 - Permission to use, copy, modify, and/or distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
25 <date>Jun 30, 2000</date>
29 <refentrytitle>lwres_context</refentrytitle>
30 <manvolnum>3</manvolnum>
31 <refmiscinfo>BIND9</refmiscinfo>
40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
46 <holder>Internet Software Consortium.</holder>
51 <refname>lwres_context_create</refname>
52 <refname>lwres_context_destroy</refname>
53 <refname>lwres_context_nextserial</refname>
54 <refname>lwres_context_initserial</refname>
55 <refname>lwres_context_freemem</refname>
56 <refname>lwres_context_allocmem</refname>
57 <refname>lwres_context_sendrecv</refname>
58 <refpurpose>lightweight resolver context management</refpurpose>
62 <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
66 <function>lwres_context_create</function></funcdef>
67 <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
68 <paramdef>void *<parameter>arg</parameter></paramdef>
69 <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
70 <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
75 <function>lwres_context_destroy</function></funcdef>
76 <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
81 <function>lwres_context_initserial</function></funcdef>
82 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
83 <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
88 <function>lwres_context_nextserial</function></funcdef>
89 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
94 <function>lwres_context_freemem</function></funcdef>
95 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
96 <paramdef>void *<parameter>mem</parameter></paramdef>
97 <paramdef>size_t <parameter>len</parameter></paramdef>
102 <function>lwres_context_allocmem</function></funcdef>
103 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
104 <paramdef>size_t <parameter>len</parameter></paramdef>
109 <function>lwres_context_sendrecv</function></funcdef>
110 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
111 <paramdef>void *<parameter>sendbase</parameter></paramdef>
112 <paramdef>int <parameter>sendlen</parameter></paramdef>
113 <paramdef>void *<parameter>recvbase</parameter></paramdef>
114 <paramdef>int <parameter>recvlen</parameter></paramdef>
115 <paramdef>int *<parameter>recvd_len</parameter></paramdef>
120 <title>DESCRIPTION</title>
122 <para><function>lwres_context_create()</function>
123 creates a <type>lwres_context_t</type> structure for use in
124 lightweight resolver operations. It holds a socket and other
125 data needed for communicating with a resolver daemon. The new
126 <type>lwres_context_t</type> is returned through
127 <parameter>contextp</parameter>, a pointer to a
128 <type>lwres_context_t</type> pointer. This
129 <type>lwres_context_t</type> pointer must initially be NULL, and
130 is modified to point to the newly created
131 <type>lwres_context_t</type>.
134 When the lightweight resolver needs to perform dynamic memory
135 allocation, it will call
136 <parameter>malloc_function</parameter>
137 to allocate memory and
138 <parameter>free_function</parameter>
140 <parameter>malloc_function</parameter>
142 <parameter>free_function</parameter>
143 are NULL, memory is allocated using
145 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
149 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
152 It is not permitted to have a NULL
153 <parameter>malloc_function</parameter> and a non-NULL
154 <parameter>free_function</parameter> or vice versa.
155 <parameter>arg</parameter> is passed as the first parameter to
156 the memory allocation functions. If
157 <parameter>malloc_function</parameter> and
158 <parameter>free_function</parameter> are NULL,
159 <parameter>arg</parameter> is unused and should be passed as
164 Once memory for the structure has been allocated,
165 it is initialized using
167 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
169 and returned via <parameter>*contextp</parameter>.
172 <para><function>lwres_context_destroy()</function>
173 destroys a <type>lwres_context_t</type>, closing its socket.
174 <parameter>contextp</parameter> is a pointer to a pointer to the
175 context that is to be destroyed. The pointer will be set to
176 NULL when the context has been destroyed.
180 The context holds a serial number that is used to identify
181 resolver request packets and associate responses with the
182 corresponding requests. This serial number is controlled using
183 <function>lwres_context_initserial()</function> and
184 <function>lwres_context_nextserial()</function>.
185 <function>lwres_context_initserial()</function> sets the serial
186 number for context <parameter>*ctx</parameter> to
187 <parameter>serial</parameter>.
188 <function>lwres_context_nextserial()</function> increments the
189 serial number and returns the previous value.
193 Memory for a lightweight resolver context is allocated and freed
194 using <function>lwres_context_allocmem()</function> and
195 <function>lwres_context_freemem()</function>. These use
196 whatever allocations were defined when the context was created
197 with <function>lwres_context_create()</function>.
198 <function>lwres_context_allocmem()</function> allocates
199 <parameter>len</parameter> bytes of memory and if successful
200 returns a pointer to the allocated storage.
201 <function>lwres_context_freemem()</function> frees
202 <parameter>len</parameter> bytes of space starting at location
203 <parameter>mem</parameter>.
206 <para><function>lwres_context_sendrecv()</function>
207 performs I/O for the context <parameter>ctx</parameter>. Data
208 are read and written from the context's socket. It writes data
209 from <parameter>sendbase</parameter> — typically a
210 lightweight resolver query packet — and waits for a reply
211 which is copied to the receive buffer at
212 <parameter>recvbase</parameter>. The number of bytes that were
213 written to this receive buffer is returned in
214 <parameter>*recvd_len</parameter>.
219 <title>RETURN VALUES</title>
221 <para><function>lwres_context_create()</function>
222 returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
223 the <type>struct lwres_context</type> could not be allocated,
224 <errorcode>LWRES_R_SUCCESS</errorcode> otherwise.
227 Successful calls to the memory allocator
228 <function>lwres_context_allocmem()</function>
229 return a pointer to the start of the allocated space.
230 It returns NULL if memory could not be allocated.
232 <para><errorcode>LWRES_R_SUCCESS</errorcode>
234 <function>lwres_context_sendrecv()</function>
235 completes successfully.
236 <errorcode>LWRES_R_IOERROR</errorcode>
237 is returned if an I/O error occurs and
238 <errorcode>LWRES_R_TIMEOUT</errorcode>
240 <function>lwres_context_sendrecv()</function>
241 times out waiting for a response.
245 <title>SEE ALSO</title>
247 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
251 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
255 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>