/contrib/bind9/lib/lwres/man/lwres_context.docbook
Unknown | 263 lines | 247 code | 16 blank | 0 comment | 0 complexity | 170b2ff398e9d82d9cc71c657de631ed MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
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, 2012 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<!-- $Id$ --> 22<refentry> 23 24 <refentryinfo> 25 <date>Jun 30, 2000</date> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle>lwres_context</refentrytitle> 30 <manvolnum>3</manvolnum> 31 <refmiscinfo>BIND9</refmiscinfo> 32 </refmeta> 33 34 <docinfo> 35 <copyright> 36 <year>2004</year> 37 <year>2005</year> 38 <year>2007</year> 39 <year>2012</year> 40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 41 </copyright> 42 <copyright> 43 <year>2000</year> 44 <year>2001</year> 45 <year>2003</year> 46 <holder>Internet Software Consortium.</holder> 47 </copyright> 48 </docinfo> 49 50 <refnamediv> 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> 59 </refnamediv> 60 <refsynopsisdiv> 61 <funcsynopsis> 62<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> 63<funcprototype> 64 <funcdef> 65lwres_result_t 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> 71 </funcprototype> 72<funcprototype> 73 <funcdef> 74lwres_result_t 75<function>lwres_context_destroy</function></funcdef> 76 <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef> 77 </funcprototype> 78<funcprototype> 79 <funcdef> 80void 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> 84 </funcprototype> 85<funcprototype> 86 <funcdef> 87lwres_uint32_t 88<function>lwres_context_nextserial</function></funcdef> 89 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 90 </funcprototype> 91<funcprototype> 92 <funcdef> 93void 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> 98 </funcprototype> 99<funcprototype> 100 <funcdef> 101void 102<function>lwres_context_allocmem</function></funcdef> 103 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 104 <paramdef>size_t <parameter>len</parameter></paramdef> 105 </funcprototype> 106<funcprototype> 107 <funcdef> 108void * 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> 116 </funcprototype> 117</funcsynopsis> 118 </refsynopsisdiv> 119 <refsect1> 120 <title>DESCRIPTION</title> 121 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>. 132 </para> 133 <para> 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> 139 to free it. If 140 <parameter>malloc_function</parameter> 141 and 142 <parameter>free_function</parameter> 143 are NULL, memory is allocated using 144 <citerefentry> 145 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> 146 </citerefentry>. 147 and 148 <citerefentry> 149 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> 150 </citerefentry>. 151 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 160 NULL. 161 </para> 162 163 <para> 164 Once memory for the structure has been allocated, 165 it is initialized using 166 <citerefentry> 167 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> 168 </citerefentry> 169 and returned via <parameter>*contextp</parameter>. 170 </para> 171 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. 177 </para> 178 179 <para> 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. 190 </para> 191 192 <para> 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>. 204 </para> 205 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>. 215 </para> 216 </refsect1> 217 218 <refsect1> 219 <title>RETURN VALUES</title> 220 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. 225 </para> 226 <para> 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. 231 </para> 232 <para><errorcode>LWRES_R_SUCCESS</errorcode> 233 is returned when 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> 239 is returned if 240 <function>lwres_context_sendrecv()</function> 241 times out waiting for a response. 242 </para> 243 </refsect1> 244 <refsect1> 245 <title>SEE ALSO</title> 246 <para><citerefentry> 247 <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> 248 </citerefentry>, 249 250 <citerefentry> 251 <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> 252 </citerefentry>, 253 254 <citerefentry> 255 <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> 256 </citerefentry>. 257 </para> 258 </refsect1> 259</refentry><!-- 260 - Local variables: 261 - mode: sgml 262 - End: 263-->