lwres_context.docbook revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
c30ef289fe64ac7fedc44cfcc6b439f0f8458b4cgregames<!ENTITY mdash "—">]>
5541a81e194dc99521c0ecf904a940b0b65a93f2nd - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
5647769dc9969e353cff0c3b116c2cd9fac1538end - This Source Code Form is subject to the terms of the Mozilla Public
5647769dc9969e353cff0c3b116c2cd9fac1538end - License, v. 2.0. If a copy of the MPL was not distributed with this
5647769dc9969e353cff0c3b116c2cd9fac1538end - file, You can obtain one at http://mozilla.org/MPL/2.0/.
264b2c09c3e55b3f60af6d1b7de9194a71da1d41nd<!-- Converted by db4-upgrade version 1.0 -->
547ee8ac5582011ae705038b6cca8c339a155b30nd<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
219e31b849ef108cd8f58ba0eedae03414e5edb1thommay <refentryinfo>
a98959721afc481c7f3a941f85c462f0b90defdathommay <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
a98959721afc481c7f3a941f85c462f0b90defdathommay </refentryinfo>
dbb916b882c33a4e340b0dba7d75506cfdd85640trawick <copyright>
2dd92c6a9669e0e180f9f2fc9799cf5cf3167534trawick <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
acc3e80f96b099467531887979ace7d8957f807ctrawick </copyright>
acc3e80f96b099467531887979ace7d8957f807ctrawick <copyright>
ffd0d55dc34cf4caada15d09018c7d915e5736a3wrowe </copyright>
9098f795fab5db41a52b6b82fa475e8f9b3850f0trawick <refnamediv>
5d2959154eb0b63ab0e9ef5fc2c34f296fa7beeegregames <refpurpose>lightweight resolver context management</refpurpose>
5d2959154eb0b63ab0e9ef5fc2c34f296fa7beeegregames </refnamediv>
81b30d1b974212267ddc27c450abc1453ce56423nd <refsynopsisdiv>
81b30d1b974212267ddc27c450abc1453ce56423nd <funcsynopsis>
81b30d1b974212267ddc27c450abc1453ce56423nd<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
fc25339741311efd7d460f18b6287ef38d76bbe6madhum<funcprototype>
fc25339741311efd7d460f18b6287ef38d76bbe6madhumlwres_result_t
fcdca175a52fe517f2317ba0e2b6e6d14522b869madhum <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
fcdca175a52fe517f2317ba0e2b6e6d14522b869madhum <paramdef>void *<parameter>arg</parameter></paramdef>
92a2439559cf1161742650ed9c50c6483bd029cemadhum <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef>
92a2439559cf1161742650ed9c50c6483bd029cemadhum <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef>
92a2439559cf1161742650ed9c50c6483bd029cemadhum </funcprototype>
92a2439559cf1161742650ed9c50c6483bd029cemadhum<funcprototype>
0d60370bedd05f9632f54e85c417ce472d463674madhumlwres_result_t
0d60370bedd05f9632f54e85c417ce472d463674madhum <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef>
ebecc16986604cce1369d5075eff65032e3dd0deianh </funcprototype>
0d60370bedd05f9632f54e85c417ce472d463674madhum<funcprototype>
764315969cef40e50cdc6a5e9638454e10c1c06end <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
764315969cef40e50cdc6a5e9638454e10c1c06end <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef>
4ac3e76f96ca3a5d0f67ae5cbe637c18f7280458gregames </funcprototype>
4ac3e76f96ca3a5d0f67ae5cbe637c18f7280458gregames<funcprototype>
bfb54bd96690887dcdf184fd9083c2e167898ce2ndlwres_uint32_t
a2c036f0ca71e35c085b4cd9451a6d3718bc65daake <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a2c036f0ca71e35c085b4cd9451a6d3718bc65daake </funcprototype>
a2c036f0ca71e35c085b4cd9451a6d3718bc65daake<funcprototype>
b92cba59a0890be43b14aaf1ce30606140be9593nd <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
402d23baca89e8c4fcb4e52ad8b2d66a6904baaetrawick <paramdef>void *<parameter>mem</parameter></paramdef>
402d23baca89e8c4fcb4e52ad8b2d66a6904baaetrawick <paramdef>size_t <parameter>len</parameter></paramdef>
402d23baca89e8c4fcb4e52ad8b2d66a6904baaetrawick </funcprototype>
6d4bfae6836af357a3b9790c0d6a06fdd00f177fnd<funcprototype>
4caa28863a3418d26cc20a998dc368c3de3b7e19jerenkrantz <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
4caa28863a3418d26cc20a998dc368c3de3b7e19jerenkrantz <paramdef>size_t <parameter>len</parameter></paramdef>
4caa28863a3418d26cc20a998dc368c3de3b7e19jerenkrantz </funcprototype>
07af571d0ef9975db2e79cd01222effd58dbb81ejerenkrantz<funcprototype>
a3f2646ef3d8a3a5234a5601de0f95f10308c2a6jerenkrantz<function>lwres_context_sendrecv</function></funcdef>
a3f2646ef3d8a3a5234a5601de0f95f10308c2a6jerenkrantz <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a3f2646ef3d8a3a5234a5601de0f95f10308c2a6jerenkrantz <paramdef>void *<parameter>sendbase</parameter></paramdef>
9e398d701dd430f073ff5418fb720642e064046ajerenkrantz <paramdef>int <parameter>sendlen</parameter></paramdef>
9e398d701dd430f073ff5418fb720642e064046ajerenkrantz <paramdef>void *<parameter>recvbase</parameter></paramdef>
9e398d701dd430f073ff5418fb720642e064046ajerenkrantz <paramdef>int <parameter>recvlen</parameter></paramdef>
1a5b9e0071f0c662036250b482d566ad87ff0b4bjerenkrantz <paramdef>int *<parameter>recvd_len</parameter></paramdef>
1a5b9e0071f0c662036250b482d566ad87ff0b4bjerenkrantz </funcprototype>
1a5b9e0071f0c662036250b482d566ad87ff0b4bjerenkrantz</funcsynopsis>
a7ac9b52c3d9f7ce937f078a0d585023db626c55jerenkrantz </refsynopsisdiv>
a7ac9b52c3d9f7ce937f078a0d585023db626c55jerenkrantz <refsection><info><title>DESCRIPTION</title></info>
ba6c07204bd224fa5d4cd0e6b8bf256d6daffb74nd creates a <type>lwres_context_t</type> structure for use in
db5837bbc9bef214303e755fa52122140366cb6fianh lightweight resolver operations. It holds a socket and other
db5837bbc9bef214303e755fa52122140366cb6fianh data needed for communicating with a resolver daemon. The new
aac2b82fe4f1ac117e2a0702438d6615542642dand <type>lwres_context_t</type> pointer must initially be NULL, and
a793d402c74e50326a2401cfbdc562c5781948fdnd is modified to point to the newly created
99d360dcbb5ac2be27694be74cc6124dbadf3315jerenkrantz When the lightweight resolver needs to perform dynamic memory
99d360dcbb5ac2be27694be74cc6124dbadf3315jerenkrantz allocation, it will call
3ded62d7f2c9b12616d718b8c97d3044baa9ecdbjerenkrantz to allocate memory and
3ded62d7f2c9b12616d718b8c97d3044baa9ecdbjerenkrantz to free it. If
031acbd88cdb9051f474a38ef67ca403cb7039b3nd are NULL, memory is allocated using
ab8c0315521735c73ce16c8072f91e17c406ca5bnd <citerefentry>
ab8c0315521735c73ce16c8072f91e17c406ca5bnd <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
ab8c0315521735c73ce16c8072f91e17c406ca5bnd </citerefentry>.
b9e99e0d3154bbebe3e1b8d11d6c15bde79510a5nd <citerefentry>
b9e99e0d3154bbebe3e1b8d11d6c15bde79510a5nd <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
b9e99e0d3154bbebe3e1b8d11d6c15bde79510a5nd </citerefentry>.
ea5f8cfbb7ef1d19318f6994c26dd73c38ffd8ddjerenkrantz It is not permitted to have a NULL
ea5f8cfbb7ef1d19318f6994c26dd73c38ffd8ddjerenkrantz <parameter>malloc_function</parameter> and a non-NULL
4567cfc6a65328bd3e8dd2b758ca926b389c7058brianp <parameter>arg</parameter> is passed as the first parameter to
4567cfc6a65328bd3e8dd2b758ca926b389c7058brianp the memory allocation functions. If
4cdc5446050c19b9d519a273a129188586e8d445jerenkrantz <parameter>arg</parameter> is unused and should be passed as
d5b7ba26785d7494166d48876362ba30ff30b98awrowe Once memory for the structure has been allocated,
47fe07199bddec6124ab7251c6be5c6c9ac00485jerenkrantz it is initialized using
47fe07199bddec6124ab7251c6be5c6c9ac00485jerenkrantz <citerefentry>
6646a289c2d4778c8cd43d62b5a1cc966a356f85jerenkrantz <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
6646a289c2d4778c8cd43d62b5a1cc966a356f85jerenkrantz </citerefentry>
6646a289c2d4778c8cd43d62b5a1cc966a356f85jerenkrantz and returned via <parameter>*contextp</parameter>.
aec70520ebe1e33e0d5e83c3626649d2a41dbe68wrowe destroys a <type>lwres_context_t</type>, closing its socket.
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe <parameter>contextp</parameter> is a pointer to a pointer to the
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe context that is to be destroyed. The pointer will be set to
ad451e2e428a069086d1c18c9e3372f8846ec617wrowe NULL when the context has been destroyed.
340e970018246649e86dd3ebbd34f4719e3ceaf7trawick The context holds a serial number that is used to identify
340e970018246649e86dd3ebbd34f4719e3ceaf7trawick resolver request packets and associate responses with the
340e970018246649e86dd3ebbd34f4719e3ceaf7trawick corresponding requests. This serial number is controlled using
1360e9b0036040edfbcd2273ae18db83a93536detrawick <function>lwres_context_initserial()</function> sets the serial
1360e9b0036040edfbcd2273ae18db83a93536detrawick <function>lwres_context_nextserial()</function> increments the
1360e9b0036040edfbcd2273ae18db83a93536detrawick serial number and returns the previous value.
c3f32ea297c5350948a0c4472c1ff8433ea4e6bastoddard Memory for a lightweight resolver context is allocated and freed
c3f32ea297c5350948a0c4472c1ff8433ea4e6bastoddard using <function>lwres_context_allocmem()</function> and
c3f32ea297c5350948a0c4472c1ff8433ea4e6bastoddard <function>lwres_context_freemem()</function>. These use
946f7bd76a0dec6d67af79af56a8cff3cb6ef9c1nd whatever allocations were defined when the context was created
946f7bd76a0dec6d67af79af56a8cff3cb6ef9c1nd <parameter>len</parameter> bytes of memory and if successful
8c038cdb417502a969599568ccc4020576d82a10nd returns a pointer to the allocated storage.
8c038cdb417502a969599568ccc4020576d82a10nd <parameter>len</parameter> bytes of space starting at location
8c038cdb417502a969599568ccc4020576d82a10nd performs I/O for the context <parameter>ctx</parameter>. Data
83938932cb2dbe320eda488799bb7a0c04156bcdake are read and written from the context's socket. It writes data
83938932cb2dbe320eda488799bb7a0c04156bcdake from <parameter>sendbase</parameter> — typically a
83938932cb2dbe320eda488799bb7a0c04156bcdake lightweight resolver query packet — and waits for a reply
83938932cb2dbe320eda488799bb7a0c04156bcdake which is copied to the receive buffer at
6fbf645df300ffa9c9693399571f2cd821af06fdtrawick <parameter>recvbase</parameter>. The number of bytes that were
6fbf645df300ffa9c9693399571f2cd821af06fdtrawick written to this receive buffer is returned in
6fbf645df300ffa9c9693399571f2cd821af06fdtrawick </refsection>
c8ff8621370eb28a3f697a00bf5e6b3bc1a0d9f1minfrin <refsection><info><title>RETURN VALUES</title></info>
c8989f842c2ad4533950c13d99d3dfb099da0d67minfrin returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for
c8989f842c2ad4533950c13d99d3dfb099da0d67minfrin the <type>struct lwres_context</type> could not be allocated,
97610ac677a5eda4a3bb366c5bb34a27eeb4288cminfrin Successful calls to the memory allocator
6aa783d83f4304f664233d8252cb67116769676ewrowe return a pointer to the start of the allocated space.
6aa783d83f4304f664233d8252cb67116769676ewrowe It returns NULL if memory could not be allocated.
6aa783d83f4304f664233d8252cb67116769676ewrowe is returned when
761fb8d21084bd7b7eb590fbd54a925dfdf806bbnd completes successfully.
761fb8d21084bd7b7eb590fbd54a925dfdf806bbnd is returned if an I/O error occurs and
761fb8d21084bd7b7eb590fbd54a925dfdf806bbnd is returned if
761fb8d21084bd7b7eb590fbd54a925dfdf806bbnd times out waiting for a response.
761fb8d21084bd7b7eb590fbd54a925dfdf806bbnd </refsection>
d8f54fe5534b61afa68100dddbe2eb98285d1100wrowe <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
d8f54fe5534b61afa68100dddbe2eb98285d1100wrowe </citerefentry>,
d8f54fe5534b61afa68100dddbe2eb98285d1100wrowe <citerefentry>
d8f54fe5534b61afa68100dddbe2eb98285d1100wrowe <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
6aa783d83f4304f664233d8252cb67116769676ewrowe </citerefentry>,
6aa783d83f4304f664233d8252cb67116769676ewrowe <citerefentry>
d8f54fe5534b61afa68100dddbe2eb98285d1100wrowe <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
18f36c8bdc74f9fd18739b9a154852c541b18900minfrin </citerefentry>.
18f36c8bdc74f9fd18739b9a154852c541b18900minfrin </refsection>