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 "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. 7 - 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. 11 - 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. 19--> 20 21<refentry> 22 23 <refentryinfo> 24 <date>June 18, 2007</date> 25 </refentryinfo> 26 27 <refmeta> 28 <refentrytitle>lwres_context</refentrytitle> 29 <manvolnum>3</manvolnum> 30 <refmiscinfo>BIND9</refmiscinfo> 31 </refmeta> 32 33 <docinfo> 34 <copyright> 35 <year>2004</year> 36 <year>2005</year> 37 <year>2007</year> 38 <year>2014</year> 39 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 40 </copyright> 41 <copyright> 42 <year>2000</year> 43 <year>2001</year> 44 <year>2003</year> 45 <holder>Internet Software Consortium.</holder> 46 </copyright> 47 </docinfo> 48 49 <refnamediv> 50 <refname>lwres_context_create</refname> 51 <refname>lwres_context_destroy</refname> 52 <refname>lwres_context_nextserial</refname> 53 <refname>lwres_context_initserial</refname> 54 <refname>lwres_context_freemem</refname> 55 <refname>lwres_context_allocmem</refname> 56 <refname>lwres_context_sendrecv</refname> 57 <refpurpose>lightweight resolver context management</refpurpose> 58 </refnamediv> 59 <refsynopsisdiv> 60 <funcsynopsis> 61<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> 62<funcprototype> 63 <funcdef> 64lwres_result_t 65<function>lwres_context_create</function></funcdef> 66 <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef> 67 <paramdef>void *<parameter>arg</parameter></paramdef> 68 <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef> 69 <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef> 70 </funcprototype> 71<funcprototype> 72 <funcdef> 73lwres_result_t 74<function>lwres_context_destroy</function></funcdef> 75 <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef> 76 </funcprototype> 77<funcprototype> 78 <funcdef> 79void 80<function>lwres_context_initserial</function></funcdef> 81 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 82 <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef> 83 </funcprototype> 84<funcprototype> 85 <funcdef> 86lwres_uint32_t 87<function>lwres_context_nextserial</function></funcdef> 88 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 89 </funcprototype> 90<funcprototype> 91 <funcdef> 92void 93<function>lwres_context_freemem</function></funcdef> 94 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 95 <paramdef>void *<parameter>mem</parameter></paramdef> 96 <paramdef>size_t <parameter>len</parameter></paramdef> 97 </funcprototype> 98<funcprototype> 99 <funcdef> 100void 101<function>lwres_context_allocmem</function></funcdef> 102 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 103 <paramdef>size_t <parameter>len</parameter></paramdef> 104 </funcprototype> 105<funcprototype> 106 <funcdef> 107void * 108<function>lwres_context_sendrecv</function></funcdef> 109 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 110 <paramdef>void *<parameter>sendbase</parameter></paramdef> 111 <paramdef>int <parameter>sendlen</parameter></paramdef> 112 <paramdef>void *<parameter>recvbase</parameter></paramdef> 113 <paramdef>int <parameter>recvlen</parameter></paramdef> 114 <paramdef>int *<parameter>recvd_len</parameter></paramdef> 115 </funcprototype> 116</funcsynopsis> 117 </refsynopsisdiv> 118 <refsect1> 119 <title>DESCRIPTION</title> 120 121 <para><function>lwres_context_create()</function> 122 creates a <type>lwres_context_t</type> structure for use in 123 lightweight resolver operations. It holds a socket and other 124 data needed for communicating with a resolver daemon. The new 125 <type>lwres_context_t</type> is returned through 126 <parameter>contextp</parameter>, a pointer to a 127 <type>lwres_context_t</type> pointer. This 128 <type>lwres_context_t</type> pointer must initially be NULL, and 129 is modified to point to the newly created 130 <type>lwres_context_t</type>. 131 </para> 132 <para> 133 When the lightweight resolver needs to perform dynamic memory 134 allocation, it will call 135 <parameter>malloc_function</parameter> 136 to allocate memory and 137 <parameter>free_function</parameter> 138 to free it. If 139 <parameter>malloc_function</parameter> 140 and 141 <parameter>free_function</parameter> 142 are NULL, memory is allocated using 143 <citerefentry> 144 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> 145 </citerefentry>. 146 and 147 <citerefentry> 148 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> 149 </citerefentry>. 150 151 It is not permitted to have a NULL 152 <parameter>malloc_function</parameter> and a non-NULL 153 <parameter>free_function</parameter> or vice versa. 154 <parameter>arg</parameter> is passed as the first parameter to 155 the memory allocation functions. If 156 <parameter>malloc_function</parameter> and 157 <parameter>free_function</parameter> are NULL, 158 <parameter>arg</parameter> is unused and should be passed as 159 NULL. 160 </para> 161 162 <para> 163 Once memory for the structure has been allocated, 164 it is initialized using 165 <citerefentry> 166 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> 167 </citerefentry> 168 and returned via <parameter>*contextp</parameter>. 169 </para> 170 171 <para><function>lwres_context_destroy()</function> 172 destroys a <type>lwres_context_t</type>, closing its socket. 173 <parameter>contextp</parameter> is a pointer to a pointer to the 174 context that is to be destroyed. The pointer will be set to 175 NULL when the context has been destroyed. 176 </para> 177 178 <para> 179 The context holds a serial number that is used to identify 180 resolver request packets and associate responses with the 181 corresponding requests. This serial number is controlled using 182 <function>lwres_context_initserial()</function> and 183 <function>lwres_context_nextserial()</function>. 184 <function>lwres_context_initserial()</function> sets the serial 185 number for context <parameter>*ctx</parameter> to 186 <parameter>serial</parameter>. 187 <function>lwres_context_nextserial()</function> increments the 188 serial number and returns the previous value. 189 </para> 190 191 <para> 192 Memory for a lightweight resolver context is allocated and freed 193 using <function>lwres_context_allocmem()</function> and 194 <function>lwres_context_freemem()</function>. These use 195 whatever allocations were defined when the context was created 196 with <function>lwres_context_create()</function>. 197 <function>lwres_context_allocmem()</function> allocates 198 <parameter>len</parameter> bytes of memory and if successful 199 returns a pointer to the allocated storage. 200 <function>lwres_context_freemem()</function> frees 201 <parameter>len</parameter> bytes of space starting at location 202 <parameter>mem</parameter>. 203 </para> 204 205 <para><function>lwres_context_sendrecv()</function> 206 performs I/O for the context <parameter>ctx</parameter>. Data 207 are read and written from the context's socket. It writes data 208 from <parameter>sendbase</parameter> — typically a 209 lightweight resolver query packet — and waits for a reply 210 which is copied to the receive buffer at 211 <parameter>recvbase</parameter>. The number of bytes that were 212 written to this receive buffer is returned in 213 <parameter>*recvd_len</parameter>. 214 </para> 215 </refsect1> 216 217 <refsect1> 218 <title>RETURN VALUES</title> 219 220 <para><function>lwres_context_create()</function> 221 returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for 222 the <type>struct lwres_context</type> could not be allocated, 223 <errorcode>LWRES_R_SUCCESS</errorcode> otherwise. 224 </para> 225 <para> 226 Successful calls to the memory allocator 227 <function>lwres_context_allocmem()</function> 228 return a pointer to the start of the allocated space. 229 It returns NULL if memory could not be allocated. 230 </para> 231 <para><errorcode>LWRES_R_SUCCESS</errorcode> 232 is returned when 233 <function>lwres_context_sendrecv()</function> 234 completes successfully. 235 <errorcode>LWRES_R_IOERROR</errorcode> 236 is returned if an I/O error occurs and 237 <errorcode>LWRES_R_TIMEOUT</errorcode> 238 is returned if 239 <function>lwres_context_sendrecv()</function> 240 times out waiting for a response. 241 </para> 242 </refsect1> 243 <refsect1> 244 <title>SEE ALSO</title> 245 <para><citerefentry> 246 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> 247 </citerefentry>, 248 249 <citerefentry> 250 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> 251 </citerefentry>, 252 253 <citerefentry> 254 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> 255 </citerefentry>. 256 </para> 257 </refsect1> 258</refentry><!-- 259 - Local variables: 260 - mode: sgml 261 - End: 262--> 263