lwres_context.html revision 61e1dc26d62c2a0059e3ca7efe2ad0f4a5b8df92
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
61e1dc26d62c2a0059e3ca7efe2ad0f4a5b8df92Mark Andrews - Copyright (C) 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
61e1dc26d62c2a0059e3ca7efe2ad0f4a5b8df92Mark Andrews<!-- $Id: lwres_context.html,v 1.9 2004/04/07 00:57:02 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
3970098dcd2a7122541667b4b56cea8abce8ccf2Mark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBGCOLOR="#FFFFFF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonVLINK="#840084"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonALINK="#0000FF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context</A
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFNAMEDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>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</DIV
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSYNOPSISDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSIS"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSISINFO"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_create</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_destroy</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t **contextp);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_initserial</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_uint32_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_nextserial</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_freemem</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, void *mem, size_t len);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_allocmem</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, size_t len);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_context_sendrecv</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>DESCRIPTION</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_create()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure for use in lightweight resolver operations.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt holds a socket and other data needed for communicating
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwith a resolver daemon.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
3970098dcd2a7122541667b4b56cea8abce8ccf2Mark Andrewsis returned through
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonpointer must initially be NULL, and is modified
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto point to the newly created
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>When the lightweight resolver needs to perform dynamic memory
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonallocation, it will call
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>malloc_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto allocate memory and
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>free_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>malloc_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>free_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonare NULL, memory is allocated using
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt is not permitted to have a NULL
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>malloc_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>free_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis passed as the first parameter to the memory
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonallocation functions.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>malloc_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>free_function</I
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis unused and should be passed as NULL.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Once memory for the structure has been allocated,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonit is initialized using
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_conf_init</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand returned via
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_destroy()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonclosing its socket.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a pointer to a pointer to the context that is to be destroyed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe pointer will be set to NULL when the context has been destroyed.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The context holds a serial number that is used to identify resolver
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrequest packets and associate responses with the corresponding requests.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis serial number is controlled using
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_initserial()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_nextserial()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_initserial()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonsets the serial number for context
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_nextserial()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonincrements the serial number and returns the previous value.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Memory for a lightweight resolver context is allocated and freed using
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_allocmem()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_freemem()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese use whatever allocations were defined when the context was
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_create()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_allocmem()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes of memory and if successful returns a pointer to the allocated
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_freemem()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonbytes of space starting at location
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_sendrecv()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms I/O for the context
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonData are read and written from the context's socket.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt writes data from
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson— typically a lightweight resolver query packet —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand waits for a reply which is copied to the receive buffer at
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe number of bytes that were written to this receive buffer is
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>RETURN VALUES</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_create()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_NOMEMORY</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif memory for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct lwres_context</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncould not be allocated,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Successful calls to the memory allocator
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_allocmem()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturn a pointer to the start of the allocated space.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt returns NULL if memory could not be allocated.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned when
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_sendrecv()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncompletes successfully.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_IOERROR</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned if an I/O error occurs and
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_TIMEOUT</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_context_sendrecv()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontimes out waiting for a response.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_conf_init</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"