lwres_context.html revision fd2597f75693a2279fdf588bd40dfe2407c42028
ec79b29695b183f794264bbb578c51e93d1f9b1emartin - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
6aa2272cc4af77e605ba2c4a4781f8567408b7e3pquerna - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh - Permission to use, copy, modify, and/or distribute this software for any
9d129b55f5a43abf43865c6b0eb6dd19bc22aba8ianh - purpose with or without fee is hereby granted, provided that the above
372d7ae4deae06dcd35151a21d22e2a4ad8fed52colm - copyright notice and this permission notice appear in all copies.
372d7ae4deae06dcd35151a21d22e2a4ad8fed52colm - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
372d7ae4deae06dcd35151a21d22e2a4ad8fed52colm - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
3e31296f734b08ad1e536cf6a1198b8cdb6d0d22colm - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
1c223a87ddbe004229f784c72d64d1a6d8487bcccolm - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
1c223a87ddbe004229f784c72d64d1a6d8487bcccolm - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
1c223a87ddbe004229f784c72d64d1a6d8487bcccolm - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
372d7ae4deae06dcd35151a21d22e2a4ad8fed52colm - PERFORMANCE OF THIS SOFTWARE.
7b621044ee03c0c140c2ba6fdab7d2dfdb2b9f4acolm<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7b621044ee03c0c140c2ba6fdab7d2dfdb2b9f4acolm<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
89ebbccde2b87b469b9d6fdb606eeb943c12a824colm<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
b38565306421ff53e9f7499bc728d6df5cec294dpquerna<p>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv — lightweight resolver context management</p>
dface6840439ab84a36749f40e7773ebfdc2066ejorton<pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
dface6840439ab84a36749f40e7773ebfdc2066ejorton<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
dface6840439ab84a36749f40e7773ebfdc2066ejortonlwres_result_t
1febae173a82bc2a71c3c0ba4105cf674000791bjim<td>lwres_context_t **<var class="pdparam">contextp</var>, </td>
454d060a0d7b13606978c536f632be71e311959djerenkrantz<td>lwres_malloc_t <var class="pdparam">malloc_function</var>, </td>
1392b9997000dceb6aca39da0a1e6405ccb6f0a6jerenkrantz<td>lwres_free_t <var class="pdparam">free_function</var><code>)</code>;</td>
4b0a0ae3fd77f8fc8fd2a693be33ffe4d99cb94ajerenkrantz<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
4b0a0ae3fd77f8fc8fd2a693be33ffe4d99cb94ajerenkrantzlwres_result_t
4b0a0ae3fd77f8fc8fd2a693be33ffe4d99cb94ajerenkrantz<b class="fsfunc">lwres_context_destroy</b>(</code></td>
4b0a0ae3fd77f8fc8fd2a693be33ffe4d99cb94ajerenkrantz<td>lwres_context_t **<var class="pdparam">contextp</var><code>)</code>;</td>
ee508128c414648982d1cca7801f63b01a0a4f8aminfrin<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
f07ae092933846055c4ca046c5a65de83d79c9c6pquerna<b class="fsfunc">lwres_context_initserial</b>(</code></td>
9b88ec397b4155f3ff79bf7c08de5f15d21765b3pquerna<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
a42c13195a5c68d55f6b2bbf5b5e1e66ab45d5d4pquerna<td>lwres_uint32_t <var class="pdparam">serial</var><code>)</code>;</td>
2a90918318af50d5712ae7159e5625476332c184pquerna<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr>
ede0584e7ec53cc1ea832c5c50281431d9ecc576pquernalwres_uint32_t
ede0584e7ec53cc1ea832c5c50281431d9ecc576pquerna<b class="fsfunc">lwres_context_nextserial</b>(</code></td>
ede0584e7ec53cc1ea832c5c50281431d9ecc576pquerna<td>lwres_context_t *<var class="pdparam">ctx</var><code>)</code>;</td>
4d3ee33c1047b89e2860fbf095c77ad245910983wrowe<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
4ec8ec67d57d820b15807fa4a23ddd0c351fa9efwrowe<b class="fsfunc">lwres_context_freemem</b>(</code></td>
4d3ee33c1047b89e2860fbf095c77ad245910983wrowe<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
42167da203d969a1402cf7ce09c14586c04af1dfjim<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
e62b34b26eb8e82bf6f06ff99a08e304b48792ecpquerna<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
27420b7ba57bf78f7a85b19fb0155053a3aff80dwrowe<b class="fsfunc">lwres_context_allocmem</b>(</code></td>
ceeb4b77f172b9d0125f1b4b323675d700b2c43bminfrin<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
9152b0c4366af633c4b7982af01bd9a821f410d5pquerna<td>size_t <var class="pdparam">len</var><code>)</code>;</td>
87d944bf70927764edf8ef69e46d3b4b8fa09131pquerna<table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
4375cabac8fc22b3717687ffdbce9bbdf095f255trawick<b class="fsfunc">lwres_context_sendrecv</b>(</code></td>
4375cabac8fc22b3717687ffdbce9bbdf095f255trawick<td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
007ba11dc68651df7f872f35947ae82a595d9e02pquerna<td>int *<var class="pdparam">recvd_len</var><code>)</code>;</td>
44ca834b970b454b844efb96f219bdf49fee71e5trawick<p><code class="function">lwres_context_create()</code>
44ca834b970b454b844efb96f219bdf49fee71e5trawick creates a <span class="type">lwres_context_t</span> structure for use in
eb8430fd3bc941c0b3ba8bba3884b7fc464bf458pquerna lightweight resolver operations. It holds a socket and other
eb8430fd3bc941c0b3ba8bba3884b7fc464bf458pquerna data needed for communicating with a resolver daemon. The new
eb8430fd3bc941c0b3ba8bba3884b7fc464bf458pquerna <span class="type">lwres_context_t</span> is returned through
1f9e65264b1ff249fa071e6aae32c0bb52f9c634trawick <em class="parameter"><code>contextp</code></em>, a pointer to a
1f9e65264b1ff249fa071e6aae32c0bb52f9c634trawick <span class="type">lwres_context_t</span> pointer. This
1f9e65264b1ff249fa071e6aae32c0bb52f9c634trawick <span class="type">lwres_context_t</span> pointer must initially be NULL, and
fde88bb682426885c679198ee130d2d5a29e8c0fbnicholes is modified to point to the newly created
fde88bb682426885c679198ee130d2d5a29e8c0fbnicholes When the lightweight resolver needs to perform dynamic memory
fde88bb682426885c679198ee130d2d5a29e8c0fbnicholes allocation, it will call
fde88bb682426885c679198ee130d2d5a29e8c0fbnicholes <em class="parameter"><code>malloc_function</code></em>
fde88bb682426885c679198ee130d2d5a29e8c0fbnicholes to allocate memory and
60e385aa992e11a6cb0504e8d4fc35186e8d848bpquerna <em class="parameter"><code>free_function</code></em>
60e385aa992e11a6cb0504e8d4fc35186e8d848bpquerna to free it. If
60e385aa992e11a6cb0504e8d4fc35186e8d848bpquerna <em class="parameter"><code>malloc_function</code></em>
d66ac514cc15e99228d72c56c6c3daf25da8d360niq are NULL, memory is allocated using
d66ac514cc15e99228d72c56c6c3daf25da8d360niq <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>.
e23b77006a8b079c0ad52e42ba2029e759455b8fjorton <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.
e23b77006a8b079c0ad52e42ba2029e759455b8fjorton It is not permitted to have a NULL
b597281295360dba8ac57b7606c5f5c1ef2b69b0trawick <em class="parameter"><code>malloc_function</code></em> and a non-NULL
b597281295360dba8ac57b7606c5f5c1ef2b69b0trawick <em class="parameter"><code>free_function</code></em> or vice versa.
b597281295360dba8ac57b7606c5f5c1ef2b69b0trawick <em class="parameter"><code>arg</code></em> is passed as the first parameter to
82d2a5debc5a6ed2118ac5916d9ba36ad0b5d78btrawick the memory allocation functions. If
82d2a5debc5a6ed2118ac5916d9ba36ad0b5d78btrawick <em class="parameter"><code>malloc_function</code></em> and
22c347c08cd77d5e2c32536b467b389fd33d631fpquerna <em class="parameter"><code>free_function</code></em> are NULL,
22c347c08cd77d5e2c32536b467b389fd33d631fpquerna <em class="parameter"><code>arg</code></em> is unused and should be passed as
b6e2b36d6972a0e243368eb567e91d511fb40b1bbnicholes Once memory for the structure has been allocated,
b6e2b36d6972a0e243368eb567e91d511fb40b1bbnicholes it is initialized using
b6e2b36d6972a0e243368eb567e91d511fb40b1bbnicholes <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>
ad4a5834dfdf9488af4ac3238ea4d8b18dce49acpquerna and returned via <em class="parameter"><code>*contextp</code></em>.
e5882a36d7756850cc829f5f2286120b877458b1pquerna<p><code class="function">lwres_context_destroy()</code>
8b7594c66e764f5cd3506b6f2459497ab65a8b03pquerna destroys a <span class="type">lwres_context_t</span>, closing its socket.
8b7594c66e764f5cd3506b6f2459497ab65a8b03pquerna <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the
8b7594c66e764f5cd3506b6f2459497ab65a8b03pquerna context that is to be destroyed. The pointer will be set to
8c46f9f81ae6357dc97560d6d85154f19cf251aejim NULL when the context has been destroyed.
20f1b1a67eef5ab0f3295608c89964a7dca4fdd1pquerna The context holds a serial number that is used to identify
20f1b1a67eef5ab0f3295608c89964a7dca4fdd1pquerna resolver request packets and associate responses with the
20f1b1a67eef5ab0f3295608c89964a7dca4fdd1pquerna corresponding requests. This serial number is controlled using
599c5abcc7fec60611956f56b732eca033c287d2pquerna <code class="function">lwres_context_initserial()</code> and
599c5abcc7fec60611956f56b732eca033c287d2pquerna <code class="function">lwres_context_nextserial()</code>.
599c5abcc7fec60611956f56b732eca033c287d2pquerna <code class="function">lwres_context_initserial()</code> sets the serial
e76fdcdfb8994ad70776526f50fa013b3e9a6033bnicholes number for context <em class="parameter"><code>*ctx</code></em> to
e76fdcdfb8994ad70776526f50fa013b3e9a6033bnicholes <code class="function">lwres_context_nextserial()</code> increments the
eb9b491d7b262dad572ec2f1f75eea592283f81apquerna serial number and returns the previous value.
c5cb4c9e7c8696907ddebab2a0037717c710b0f6jorton Memory for a lightweight resolver context is allocated and freed
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive using <code class="function">lwres_context_allocmem()</code> and
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive <code class="function">lwres_context_freemem()</code>. These use
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive whatever allocations were defined when the context was created
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive with <code class="function">lwres_context_create()</code>.
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive <code class="function">lwres_context_allocmem()</code> allocates
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive <em class="parameter"><code>len</code></em> bytes of memory and if successful
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive returns a pointer to the allocated storage.
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive <code class="function">lwres_context_freemem()</code> frees
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive <em class="parameter"><code>len</code></em> bytes of space starting at location
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive<p><code class="function">lwres_context_sendrecv()</code>
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive performs I/O for the context <em class="parameter"><code>ctx</code></em>. Data
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive are read and written from the context's socket. It writes data
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive from <em class="parameter"><code>sendbase</code></em> — typically a
6d00a5e2c08ddbff9614ecc17a1c085462811f89slive lightweight resolver query packet — and waits for a reply
4f6e78091b3f45a5782389ae25b62516a7a0c842bnicholes which is copied to the receive buffer at
4f6e78091b3f45a5782389ae25b62516a7a0c842bnicholes <em class="parameter"><code>recvbase</code></em>. The number of bytes that were
4f6e78091b3f45a5782389ae25b62516a7a0c842bnicholes written to this receive buffer is returned in
4f6e78091b3f45a5782389ae25b62516a7a0c842bnicholes <em class="parameter"><code>*recvd_len</code></em>.
e9be3aacfd6c0a1208e6c91a133be92ed0f94fe1bnicholes<p><code class="function">lwres_context_create()</code>
e9be3aacfd6c0a1208e6c91a133be92ed0f94fe1bnicholes returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for
e9be3aacfd6c0a1208e6c91a133be92ed0f94fe1bnicholes the <span class="type">struct lwres_context</span> could not be allocated,
e9be3aacfd6c0a1208e6c91a133be92ed0f94fe1bnicholes <span class="errorcode">LWRES_R_SUCCESS</span> otherwise.
6e5f5644328bf50c3aa295d0ab20903369010829gregames Successful calls to the memory allocator
6e5f5644328bf50c3aa295d0ab20903369010829gregames <code class="function">lwres_context_allocmem()</code>
6e5f5644328bf50c3aa295d0ab20903369010829gregames return a pointer to the start of the allocated space.
e978097e0bf2ae161b6f9dde40eaf089bf046c89ake It returns NULL if memory could not be allocated.
275419d6395e6f072962fb701b89accaff1f3690jerenkrantz is returned when
275419d6395e6f072962fb701b89accaff1f3690jerenkrantz <code class="function">lwres_context_sendrecv()</code>
275419d6395e6f072962fb701b89accaff1f3690jerenkrantz completes successfully.
e777da9fa7ff3138fead7860b53ef00e67a40e26jerenkrantz is returned if an I/O error occurs and
e777da9fa7ff3138fead7860b53ef00e67a40e26jerenkrantz is returned if
8bdea88407c848c1c2693655e2f8b23abde12307bnicholes <code class="function">lwres_context_sendrecv()</code>
8bdea88407c848c1c2693655e2f8b23abde12307bnicholes times out waiting for a response.
8e7fb6968047a527d1ccde25ad2aed20da5150ddjerenkrantz<p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>,
5a9fa4d75086e942f6e850e1a2e96c4c27a845d0jerenkrantz <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>,
5a9fa4d75086e942f6e850e1a2e96c4c27a845d0jerenkrantz <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>.