lwres_context.html revision 61e1dc26d62c2a0059e3ca7efe2ad0f4a5b8df92
60405de4d8688d96dd05157c28db3ade5c9bc234kz - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
60405de4d8688d96dd05157c28db3ade5c9bc234kz - Copyright (C) 2001 Internet Software Consortium.
60405de4d8688d96dd05157c28db3ade5c9bc234kz - Permission to use, copy, modify, and distribute this software for any
60405de4d8688d96dd05157c28db3ade5c9bc234kz - purpose with or without fee is hereby granted, provided that the above
60405de4d8688d96dd05157c28db3ade5c9bc234kz - copyright notice and this permission notice appear in all copies.
60405de4d8688d96dd05157c28db3ade5c9bc234kz - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60405de4d8688d96dd05157c28db3ade5c9bc234kz - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60405de4d8688d96dd05157c28db3ade5c9bc234kz - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60405de4d8688d96dd05157c28db3ade5c9bc234kz - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
60405de4d8688d96dd05157c28db3ade5c9bc234kz - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
60405de4d8688d96dd05157c28db3ade5c9bc234kz - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
60405de4d8688d96dd05157c28db3ade5c9bc234kz - PERFORMANCE OF THIS SOFTWARE.
60405de4d8688d96dd05157c28db3ade5c9bc234kz<!-- $Id: lwres_context.html,v 1.9 2004/04/07 00:57:02 marka Exp $ -->
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context</TITLE
60405de4d8688d96dd05157c28db3ade5c9bc234kzNAME="GENERATOR"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCONTENT="Modular DocBook HTML Stylesheet Version 1.73
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFENTRY"
60405de4d8688d96dd05157c28db3ade5c9bc234kzBGCOLOR="#FFFFFF"
60405de4d8688d96dd05157c28db3ade5c9bc234kzTEXT="#000000"
60405de4d8688d96dd05157c28db3ade5c9bc234kzLINK="#0000FF"
60405de4d8688d96dd05157c28db3ade5c9bc234kzVLINK="#840084"
60405de4d8688d96dd05157c28db3ade5c9bc234kzALINK="#0000FF"
e92e3a8694f157faf8a9e44096a70ada86c556bfzw>lwres_context</A
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFNAMEDIV"
60405de4d8688d96dd05157c28db3ade5c9bc234kzNAME="AEN8"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>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
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaCLASS="REFSYNOPSISDIV"
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaCLASS="FUNCSYNOPSIS"
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaCLASS="FUNCSYNOPSISINFO"
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>#include <lwres/lwres.h></PRE
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing Chinalwres_context_create</CODE
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing China>(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_destroy</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t **contextp);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_initserial</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_nextserial</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t *ctx);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_freemem</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t *ctx, void *mem, size_t len);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_allocmem</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t *ctx, size_t len);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinalwres_context_sendrecv</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaCLASS="REFSECT1"
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>DESCRIPTION</H2
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaCLASS="FUNCTION"
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>lwres_context_create()</TT
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>lwres_context_t</SPAN
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinastructure for use in lightweight resolver operations.
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing ChinaIt holds a socket and other data needed for communicating
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing Chinawith a resolver daemon.
ee33b1b8d10d92b82e8b3a266d228d3c8007f229miao chen - Sun Microsystems - Beijing China>lwres_context_t</SPAN
d02310705313ee2fcefee164a4b26d1fa85e9d22miao chen - Sun Microsystems - Beijing Chinais returned through
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kza pointer to a
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="TYPE"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>lwres_context_t</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzpointer. This
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="TYPE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_t</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzpointer must initially be NULL, and is modified
d0538f66491267879b7418b21ad78e3dcc2dcc83cgto point to the newly created
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="TYPE"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>lwres_context_t</SPAN
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>When the lightweight resolver needs to perform dynamic memory
d0538f66491267879b7418b21ad78e3dcc2dcc83cgallocation, it will call
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>malloc_function</I
d0538f66491267879b7418b21ad78e3dcc2dcc83cgto allocate memory and
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>free_function</I
d0538f66491267879b7418b21ad78e3dcc2dcc83cgto free it. If
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>malloc_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>free_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzare NULL, memory is allocated using
60405de4d8688d96dd05157c28db3ade5c9bc234kz.Xr malloc 3
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="CITEREFENTRY"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFENTRYTITLE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>free</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzIt is not permitted to have a NULL
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>malloc_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzand a non-NULL
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>free_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzor vice versa.
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzis passed as the first parameter to the memory
60405de4d8688d96dd05157c28db3ade5c9bc234kzallocation functions.
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>malloc_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>free_function</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzis unused and should be passed as NULL.</P
60405de4d8688d96dd05157c28db3ade5c9bc234kz>Once memory for the structure has been allocated,
60405de4d8688d96dd05157c28db3ade5c9bc234kzit is initialized using
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="CITEREFENTRY"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFENTRYTITLE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_conf_init</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzand returned via
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>*contextp</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_destroy()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="TYPE"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>lwres_context_t</SPAN
d0538f66491267879b7418b21ad78e3dcc2dcc83cgclosing its socket.
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>contextp</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzis a pointer to a pointer to the context that is to be destroyed.
60405de4d8688d96dd05157c28db3ade5c9bc234kzThe pointer will be set to NULL when the context has been destroyed.</P
60405de4d8688d96dd05157c28db3ade5c9bc234kz>The context holds a serial number that is used to identify resolver
60405de4d8688d96dd05157c28db3ade5c9bc234kzrequest packets and associate responses with the corresponding requests.
60405de4d8688d96dd05157c28db3ade5c9bc234kzThis serial number is controlled using
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_initserial()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_nextserial()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_initserial()</TT
d0538f66491267879b7418b21ad78e3dcc2dcc83cgsets the serial number for context
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
d02310705313ee2fcefee164a4b26d1fa85e9d22miao chen - Sun Microsystems - Beijing ChinaCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cg>lwres_context_nextserial()</TT
d0538f66491267879b7418b21ad78e3dcc2dcc83cgincrements the serial number and returns the previous value.</P
60405de4d8688d96dd05157c28db3ade5c9bc234kz>Memory for a lightweight resolver context is allocated and freed using
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_allocmem()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_freemem()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzThese use whatever allocations were defined when the context was
60405de4d8688d96dd05157c28db3ade5c9bc234kzcreated with
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing ChinaCLASS="FUNCTION"
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing China>lwres_context_create()</TT
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing ChinaCLASS="FUNCTION"
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing China>lwres_context_allocmem()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzbytes of memory and if successful returns a pointer to the allocated
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="FUNCTION"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>lwres_context_freemem()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzbytes of space starting at location
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_sendrecv()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzperforms I/O for the context
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing ChinaData are read and written from the context's socket.
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing ChinaIt writes data from
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing ChinaCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>sendbase</I
60405de4d8688d96dd05157c28db3ade5c9bc234kz— typically a lightweight resolver query packet —
60405de4d8688d96dd05157c28db3ade5c9bc234kzand waits for a reply which is copied to the receive buffer at
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="PARAMETER"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>recvbase</I
60405de4d8688d96dd05157c28db3ade5c9bc234kzThe number of bytes that were written to this receive buffer is
e92e3a8694f157faf8a9e44096a70ada86c556bfzwCLASS="PARAMETER"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFSECT1"
60405de4d8688d96dd05157c28db3ade5c9bc234kzNAME="AEN115"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>RETURN VALUES</H2
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cg>lwres_context_create()</TT
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="ERRORCODE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>LWRES_R_NOMEMORY</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzif memory for the
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="TYPE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>struct lwres_context</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzcould not be allocated,
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="ERRORCODE"
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cg>LWRES_R_SUCCESS</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzotherwise.</P
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cg>Successful calls to the memory allocator
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_allocmem()</TT
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cgreturn a pointer to the start of the allocated space.
60405de4d8688d96dd05157c28db3ade5c9bc234kzIt returns NULL if memory could not be allocated.</P
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="ERRORCODE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>LWRES_R_SUCCESS</SPAN
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cgis returned when
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="FUNCTION"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>lwres_context_sendrecv()</TT
d0538f66491267879b7418b21ad78e3dcc2dcc83cgcompletes successfully.
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="ERRORCODE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>LWRES_R_IOERROR</SPAN
60405de4d8688d96dd05157c28db3ade5c9bc234kzis returned if an I/O error occurs and
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="ERRORCODE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>LWRES_R_TIMEOUT</SPAN
d0538f66491267879b7418b21ad78e3dcc2dcc83cgis returned if
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="FUNCTION"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>lwres_context_sendrecv()</TT
d0538f66491267879b7418b21ad78e3dcc2dcc83cgtimes out waiting for a response.</P
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFSECT1"
60405de4d8688d96dd05157c28db3ade5c9bc234kzNAME="AEN130"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>SEE ALSO</H2
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="CITEREFENTRY"
60405de4d8688d96dd05157c28db3ade5c9bc234kzCLASS="REFENTRYTITLE"
0035d21c77a24d02faf34c10aabc120ca692efb5miao chen - Sun Microsystems - Beijing China>lwres_conf_init</SPAN
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="CITEREFENTRY"
d0538f66491267879b7418b21ad78e3dcc2dcc83cgCLASS="REFENTRYTITLE"
d0538f66491267879b7418b21ad78e3dcc2dcc83cg>malloc</SPAN
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cgCLASS="CITEREFENTRY"
fca314aae8ba1403ba891f2b0e7a172bcdc055c8cgCLASS="REFENTRYTITLE"
60405de4d8688d96dd05157c28db3ade5c9bc234kz>free</SPAN