2a6c49cfaef5979a5a06098f3ce987cd76769409manoj<!DOCTYPE book [

9805ac88e1befa6dea11d8513023f150d8f8e807fanf<!ENTITY mdash "&#8212;">]>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj

91a71946d0fb28c0866139edef3dd59f36ba5b9cstoddard<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">

91a71946d0fb28c0866139edef3dd59f36ba5b9cstoddard <info>

91a71946d0fb28c0866139edef3dd59f36ba5b9cstoddard <date>2007-06-18</date>

91a71946d0fb28c0866139edef3dd59f36ba5b9cstoddard </info>

91a71946d0fb28c0866139edef3dd59f36ba5b9cstoddard <refentryinfo>

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb <corpname>ISC</corpname>

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb <corpauthor>Internet Systems Consortium, Inc.</corpauthor>

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb </refentryinfo>

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb

632b0b53511f3bb9c32aa2869fbc73ee35081b38rbb <refmeta>

632b0b53511f3bb9c32aa2869fbc73ee35081b38rbb <refentrytitle>lwres_context</refentrytitle>

632b0b53511f3bb9c32aa2869fbc73ee35081b38rbb <manvolnum>3</manvolnum>

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb <refmiscinfo>BIND9</refmiscinfo>

f6a6245816cd866361da8c576b1f47c7a54b6610fanf </refmeta>

b7663b97a437dc089ac7a1a9ebd42e0c372a48b6gstein

b7663b97a437dc089ac7a1a9ebd42e0c372a48b6gstein <docinfo>

b7663b97a437dc089ac7a1a9ebd42e0c372a48b6gstein <copyright>

b7663b97a437dc089ac7a1a9ebd42e0c372a48b6gstein <year>2000</year>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <year>2001</year>

369edcdd0a9c5516c61e736ec2a6fc8fb0d92fe2manoj <year>2003</year>

369edcdd0a9c5516c61e736ec2a6fc8fb0d92fe2manoj <year>2004</year>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <year>2005</year>

85cbdc16ac57fa68ce1358a308269abcd417f4d9stoddard <year>2007</year>

85cbdc16ac57fa68ce1358a308269abcd417f4d9stoddard <year>2014</year>

85cbdc16ac57fa68ce1358a308269abcd417f4d9stoddard <year>2015</year>

d208bda4a893cc81ed5d3ed1cdd7d706e012bd42stoddard <year>2016</year>

d208bda4a893cc81ed5d3ed1cdd7d706e012bd42stoddard <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

d208bda4a893cc81ed5d3ed1cdd7d706e012bd42stoddard </copyright>

d208bda4a893cc81ed5d3ed1cdd7d706e012bd42stoddard </docinfo>

10b386767f6c87b45937244371cb751f0b454d16wrowe

10b386767f6c87b45937244371cb751f0b454d16wrowe <refnamediv>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_create</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_destroy</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_nextserial</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_initserial</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_freemem</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_allocmem</refname>

75960f20f88dad6bc67892c711c429946063d133stoddard <refname>lwres_context_sendrecv</refname>

10b386767f6c87b45937244371cb751f0b454d16wrowe <refpurpose>lightweight resolver context management</refpurpose>

10b386767f6c87b45937244371cb751f0b454d16wrowe </refnamediv>

10b386767f6c87b45937244371cb751f0b454d16wrowe <refsynopsisdiv>

10b386767f6c87b45937244371cb751f0b454d16wrowe <funcsynopsis>

10b386767f6c87b45937244371cb751f0b454d16wrowe<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>

10b386767f6c87b45937244371cb751f0b454d16wrowe<funcprototype>

10b386767f6c87b45937244371cb751f0b454d16wrowe <funcdef>

10b386767f6c87b45937244371cb751f0b454d16wrowelwres_result_t

10b386767f6c87b45937244371cb751f0b454d16wrowe<function>lwres_context_create</function></funcdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe <paramdef>void *<parameter>arg</parameter></paramdef>

a9e07e4f90adcc7bc768db3055431c3dcd560cd1manoj <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>

f6a6245816cd866361da8c576b1f47c7a54b6610fanf <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>

f6a6245816cd866361da8c576b1f47c7a54b6610fanf </funcprototype>

97b758d0b174d7b7c5a1de1a583f5840ec3fc910trawick<funcprototype>

db3ccce11afac4fc1d4f51a65424412f7480c46cgstein <funcdef>

2a6c49cfaef5979a5a06098f3ce987cd76769409manojlwres_result_t

8bed76428f56e5c643174a2d6807c3f18016af5cbjh<function>lwres_context_destroy</function></funcdef>

8bed76428f56e5c643174a2d6807c3f18016af5cbjh <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>

8bed76428f56e5c643174a2d6807c3f18016af5cbjh </funcprototype>

8bed76428f56e5c643174a2d6807c3f18016af5cbjh<funcprototype>

8bed76428f56e5c643174a2d6807c3f18016af5cbjh <funcdef>

cfc020d6d6fc9b31d8945915e65a8787a796eb73stoddardvoid

cfc020d6d6fc9b31d8945915e65a8787a796eb73stoddard<function>lwres_context_initserial</function></funcdef>

cfc020d6d6fc9b31d8945915e65a8787a796eb73stoddard <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

f824925ac58ff729289c017235eeb3bdd21ec3a2stoddard <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>

f824925ac58ff729289c017235eeb3bdd21ec3a2stoddard </funcprototype>

f824925ac58ff729289c017235eeb3bdd21ec3a2stoddard<funcprototype>

f824925ac58ff729289c017235eeb3bdd21ec3a2stoddard <funcdef>

2aae6faee508221efbeaba5547ca79b7a20ef047stoddardlwres_uint32_t

2aae6faee508221efbeaba5547ca79b7a20ef047stoddard<function>lwres_context_nextserial</function></funcdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe </funcprototype>

10b386767f6c87b45937244371cb751f0b454d16wrowe<funcprototype>

10b386767f6c87b45937244371cb751f0b454d16wrowe <funcdef>

10b386767f6c87b45937244371cb751f0b454d16wrowevoid

10b386767f6c87b45937244371cb751f0b454d16wrowe<function>lwres_context_freemem</function></funcdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

10b386767f6c87b45937244371cb751f0b454d16wrowe <paramdef>void *<parameter>mem</parameter></paramdef>

75960f20f88dad6bc67892c711c429946063d133stoddard <paramdef>size_t <parameter>len</parameter></paramdef>

a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddard </funcprototype>

a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddard<funcprototype>

a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddard <funcdef>

a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddardvoid

a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddard<function>lwres_context_allocmem</function></funcdef>

56ca30c968906053ae61acb218420667bb58d996rbb <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

56ca30c968906053ae61acb218420667bb58d996rbb <paramdef>size_t <parameter>len</parameter></paramdef>

56ca30c968906053ae61acb218420667bb58d996rbb </funcprototype>

56ca30c968906053ae61acb218420667bb58d996rbb<funcprototype>

70f6f32765cfaadd6da8de6f0fea97ddd72d8fadmanoj <funcdef>

70f6f32765cfaadd6da8de6f0fea97ddd72d8fadmanojvoid *

70f6f32765cfaadd6da8de6f0fea97ddd72d8fadmanoj<function>lwres_context_sendrecv</function></funcdef>

56ca30c968906053ae61acb218420667bb58d996rbb <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

0bff2f28ef945280c17099c142126178a78e1e54manoj <paramdef>void *<parameter>sendbase</parameter></paramdef>

0bff2f28ef945280c17099c142126178a78e1e54manoj <paramdef>int <parameter>sendlen</parameter></paramdef>

0bff2f28ef945280c17099c142126178a78e1e54manoj <paramdef>void *<parameter>recvbase</parameter></paramdef>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard <paramdef>int <parameter>recvlen</parameter></paramdef>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard <paramdef>int *<parameter>recvd_len</parameter></paramdef>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard </funcprototype>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard</funcsynopsis>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard </refsynopsisdiv>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard <refsection><info><title>DESCRIPTION</title></info>

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard

9c09943bad734ebd5c7cc10bd6d63b75c4c6e056stoddard

9c09943bad734ebd5c7cc10bd6d63b75c4c6e056stoddard <para><function>lwres_context_create()</function>

9c09943bad734ebd5c7cc10bd6d63b75c4c6e056stoddard creates a <type>lwres_context_t</type> structure for use in

0bff2f28ef945280c17099c142126178a78e1e54manoj lightweight resolver operations. It holds a socket and other

0bff2f28ef945280c17099c142126178a78e1e54manoj data needed for communicating with a resolver daemon. The new

0bff2f28ef945280c17099c142126178a78e1e54manoj <type>lwres_context_t</type> is returned through

9c09943bad734ebd5c7cc10bd6d63b75c4c6e056stoddard <parameter>contextp</parameter>, a pointer to a

75960f20f88dad6bc67892c711c429946063d133stoddard <type>lwres_context_t</type> pointer. This

1e585ba09ea32272e63c4c39c35491e975d21d98stoddard <type>lwres_context_t</type> pointer must initially be NULL, and

9c09943bad734ebd5c7cc10bd6d63b75c4c6e056stoddard is modified to point to the newly created

aa1faea36e4ae357bc603a2337b6adc54f5daec1manoj <type>lwres_context_t</type>.

f03d292915be9977eaf74e9be7b0404aec226f84manoj </para>

f03d292915be9977eaf74e9be7b0404aec226f84manoj <para>

f03d292915be9977eaf74e9be7b0404aec226f84manoj When the lightweight resolver needs to perform dynamic memory

aa1faea36e4ae357bc603a2337b6adc54f5daec1manoj allocation, it will call

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb <parameter>malloc_function</parameter>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj to allocate memory and

302dc1f7b3feee23a91ad8f3cf3cb2edd95a557bmanoj <parameter>free_function</parameter>

302dc1f7b3feee23a91ad8f3cf3cb2edd95a557bmanoj to free it. If

302dc1f7b3feee23a91ad8f3cf3cb2edd95a557bmanoj <parameter>malloc_function</parameter>

302dc1f7b3feee23a91ad8f3cf3cb2edd95a557bmanoj and

ff849e4163ed879288f0df15f78b6c9d278ec804fanf <parameter>free_function</parameter>

ff849e4163ed879288f0df15f78b6c9d278ec804fanf are NULL, memory is allocated using

9805ac88e1befa6dea11d8513023f150d8f8e807fanf <citerefentry>

9805ac88e1befa6dea11d8513023f150d8f8e807fanf <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>

9805ac88e1befa6dea11d8513023f150d8f8e807fanf </citerefentry>.

9805ac88e1befa6dea11d8513023f150d8f8e807fanf and

df4a7c143b27b489dd2d865bb3f6668c8420b3a9fanf <citerefentry>

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein </citerefentry>.

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein It is not permitted to have a NULL

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein <parameter>malloc_function</parameter> and a non-NULL

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein <parameter>free_function</parameter> or vice versa.

c03566fa0156d3a1500a42e4fe539e3e0fc8a11dgstein <parameter>arg</parameter> is passed as the first parameter to

db3ccce11afac4fc1d4f51a65424412f7480c46cgstein the memory allocation functions. If

db3ccce11afac4fc1d4f51a65424412f7480c46cgstein <parameter>malloc_function</parameter> and

db3ccce11afac4fc1d4f51a65424412f7480c46cgstein <parameter>free_function</parameter> are NULL,

db3ccce11afac4fc1d4f51a65424412f7480c46cgstein <parameter>arg</parameter> is unused and should be passed as

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj NULL.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </para>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj

d5defd5a0c5cdbaf74b85939484dc2b6c8317d19manoj <para>

d5defd5a0c5cdbaf74b85939484dc2b6c8317d19manoj Once memory for the structure has been allocated,

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj it is initialized using

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <citerefentry>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </citerefentry>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj and returned via <parameter>*contextp</parameter>.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </para>

0bff2f28ef945280c17099c142126178a78e1e54manoj

0bff2f28ef945280c17099c142126178a78e1e54manoj <para><function>lwres_context_destroy()</function>

0bff2f28ef945280c17099c142126178a78e1e54manoj destroys a <type>lwres_context_t</type>, closing its socket.

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <parameter>contextp</parameter> is a pointer to a pointer to the

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj context that is to be destroyed. The pointer will be set to

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj NULL when the context has been destroyed.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </para>

40a5b7189dbbb28e107bf008ee625f2f0142c2ccdgaudet

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <para>

dbf0c7bef06259486cd2748a2d0e82f27e099d6efielding The context holds a serial number that is used to identify

dbf0c7bef06259486cd2748a2d0e82f27e099d6efielding resolver request packets and associate responses with the

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj corresponding requests. This serial number is controlled using

bd929c73ef04789b7183b840d8db6e01d03a4d86rbb <function>lwres_context_initserial()</function> and

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <function>lwres_context_nextserial()</function>.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <function>lwres_context_initserial()</function> sets the serial

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj number for context <parameter>*ctx</parameter> to

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <parameter>serial</parameter>.

f6a6245816cd866361da8c576b1f47c7a54b6610fanf <function>lwres_context_nextserial()</function> increments the

f6a6245816cd866361da8c576b1f47c7a54b6610fanf serial number and returns the previous value.

f6a6245816cd866361da8c576b1f47c7a54b6610fanf </para>

f6a6245816cd866361da8c576b1f47c7a54b6610fanf

f6a6245816cd866361da8c576b1f47c7a54b6610fanf <para>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj Memory for a lightweight resolver context is allocated and freed

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj using <function>lwres_context_allocmem()</function> and

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <function>lwres_context_freemem()</function>. These use

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj whatever allocations were defined when the context was created

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj with <function>lwres_context_create()</function>.

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <function>lwres_context_allocmem()</function> allocates

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <parameter>len</parameter> bytes of memory and if successful

d6b3cb141f0667101c1bca883ad15b383402c93bfielding returns a pointer to the allocated storage.

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <function>lwres_context_freemem()</function> frees

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <parameter>len</parameter> bytes of space starting at location

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <parameter>mem</parameter>.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </para>

670734c2ee137c587411795c6f82566c9d3729b7coar

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <para><function>lwres_context_sendrecv()</function>

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj performs I/O for the context <parameter>ctx</parameter>. Data

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj are read and written from the context's socket. It writes data

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj from <parameter>sendbase</parameter> &mdash; typically a

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj lightweight resolver query packet &mdash; and waits for a reply

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj which is copied to the receive buffer at

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <parameter>recvbase</parameter>. The number of bytes that were

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj written to this receive buffer is returned in

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj <parameter>*recvd_len</parameter>.

2a6c49cfaef5979a5a06098f3ce987cd76769409manoj </para>

d6b3cb141f0667101c1bca883ad15b383402c93bfielding </refsection>

d6b3cb141f0667101c1bca883ad15b383402c93bfielding

d6b3cb141f0667101c1bca883ad15b383402c93bfielding <refsection><info><title>RETURN VALUES</title></info>

<para><function>lwres_context_create()</function>

returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for

the <type>struct lwres_context</type> could not be allocated,

<errorcode>LWRES_R_SUCCESS</errorcode> otherwise.

</para>

<para>

Successful calls to the memory allocator

<function>lwres_context_allocmem()</function>

return a pointer to the start of the allocated space.

It returns NULL if memory could not be allocated.

</para>

<para><errorcode>LWRES_R_SUCCESS</errorcode>

is returned when

<function>lwres_context_sendrecv()</function>

completes successfully.

<errorcode>LWRES_R_IOERROR</errorcode>

is returned if an I/O error occurs and

<errorcode>LWRES_R_TIMEOUT</errorcode>

is returned if

<function>lwres_context_sendrecv()</function>

times out waiting for a response.

</para>

</refsection>

<refsection><info><title>SEE ALSO</title></info>

<para><citerefentry>

<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>

</citerefentry>.

</para>

</refsection>

</refentry>