lwres_context.html [plain text]
<!--
- Copyright (C) 2000, 2001 Internet Software Consortium.
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->
<HTML
><HEAD
><TITLE
>lwres_context</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.73
"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
>lwres_context</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8"
></A
><H2
>Name</H2
>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
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN17"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN18"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <lwres/lwres.h></PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_context_create</CODE
>(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_result_t
lwres_context_destroy</CODE
>(lwres_context_t **contextp);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_context_initserial</CODE
>(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>lwres_uint32_t
lwres_context_nextserial</CODE
>(lwres_context_t *ctx);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_context_freemem</CODE
>(lwres_context_t *ctx, void *mem, size_t len);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_context_allocmem</CODE
>(lwres_context_t *ctx, size_t len);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void *
lwres_context_sendrecv</CODE
>(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN60"
></A
><H2
>DESCRIPTION</H2
><P
><TT
CLASS="FUNCTION"
>lwres_context_create()</TT
>
creates a
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>
structure for use in lightweight resolver operations.
It holds a socket and other data needed for communicating
with a resolver daemon.
The new
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>
is returned throught
<TT
CLASS="PARAMETER"
><I
>contextp</I
></TT
>,
a pointer to a
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>
pointer. This
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>
pointer must initially be NULL, and is modified
to point to the newly created
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>. </P
><P
>When the lightweight resolver needs to perform dynamic memory
allocation, it will call
<TT
CLASS="PARAMETER"
><I
>malloc_function</I
></TT
>
to allocate memory and
<TT
CLASS="PARAMETER"
><I
>free_function</I
></TT
>
to free it. If
<TT
CLASS="PARAMETER"
><I
>malloc_function</I
></TT
>
and
<TT
CLASS="PARAMETER"
><I
>free_function</I
></TT
>
are NULL, memory is allocated using
.Xr malloc 3
and
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>free</SPAN
>(3)</SPAN
>.
It is not permitted to have a NULL
<TT
CLASS="PARAMETER"
><I
>malloc_function</I
></TT
>
and a non-NULL
<TT
CLASS="PARAMETER"
><I
>free_function</I
></TT
>
or vice versa.
<TT
CLASS="PARAMETER"
><I
>arg</I
></TT
>
is passed as the first parameter to the memory
allocation functions.
If
<TT
CLASS="PARAMETER"
><I
>malloc_function</I
></TT
>
and
<TT
CLASS="PARAMETER"
><I
>free_function</I
></TT
>
are NULL,
<TT
CLASS="PARAMETER"
><I
>arg</I
></TT
>
is unused and should be passed as NULL.</P
><P
>Once memory for the structure has been allocated,
it is initialized using
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_conf_init</SPAN
>(3)</SPAN
>
and returned via
<TT
CLASS="PARAMETER"
><I
>*contextp</I
></TT
>. </P
><P
><TT
CLASS="FUNCTION"
>lwres_context_destroy()</TT
>
destroys a
<SPAN
CLASS="TYPE"
>lwres_context_t</SPAN
>,
closing its socket.
<TT
CLASS="PARAMETER"
><I
>contextp</I
></TT
>
is a pointer to a pointer to the context that is to be destroyed.
The pointer will be set to NULL when the context has been destroyed.</P
><P
>The context holds a serial number that is used to identify resolver
request packets and associate responses with the corresponding requests.
This serial number is controlled using
<TT
CLASS="FUNCTION"
>lwres_context_initserial()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_context_nextserial()</TT
>.
<TT
CLASS="FUNCTION"
>lwres_context_initserial()</TT
>
sets the serial number for context
<TT
CLASS="PARAMETER"
><I
>*ctx</I
></TT
>
to
<TT
CLASS="PARAMETER"
><I
>serial</I
></TT
>.
<TT
CLASS="FUNCTION"
>lwres_context_nextserial()</TT
>
increments the serial number and returns the previous value.</P
><P
>Memory for a lightweight resolver context is allocated and freed using
<TT
CLASS="FUNCTION"
>lwres_context_allocmem()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_context_freemem()</TT
>.
These use whatever allocations were defined when the context was
created with
<TT
CLASS="FUNCTION"
>lwres_context_create()</TT
>.
<TT
CLASS="FUNCTION"
>lwres_context_allocmem()</TT
>
allocates
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes of memory and if successful returns a pointer to the allocated
storage.
<TT
CLASS="FUNCTION"
>lwres_context_freemem()</TT
>
frees
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes of space starting at location
<TT
CLASS="PARAMETER"
><I
>mem</I
></TT
>. </P
><P
><TT
CLASS="FUNCTION"
>lwres_context_sendrecv()</TT
>
performs I/O for the context
<TT
CLASS="PARAMETER"
><I
>ctx</I
></TT
>.
Data are read and written from the context's socket.
It writes data from
<TT
CLASS="PARAMETER"
><I
>sendbase</I
></TT
>
— typically a lightweight resolver query packet —
and waits for a reply which is copied to the receive buffer at
<TT
CLASS="PARAMETER"
><I
>recvbase</I
></TT
>.
The number of bytes that were written to this receive buffer is
returned in
<TT
CLASS="PARAMETER"
><I
>*recvd_len</I
></TT
>. </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN115"
></A
><H2
>RETURN VALUES</H2
><P
><TT
CLASS="FUNCTION"
>lwres_context_create()</TT
>
returns
<SPAN
CLASS="ERRORCODE"
>LWRES_R_NOMEMORY</SPAN
>
if memory for the
<SPAN
CLASS="TYPE"
>struct lwres_context</SPAN
>
could not be allocated,
<SPAN
CLASS="ERRORCODE"
>LWRES_R_SUCCESS</SPAN
>
otherwise.</P
><P
>Successful calls to the memory allocator
<TT
CLASS="FUNCTION"
>lwres_context_allocmem()</TT
>
return a pointer to the start of the allocated space.
It returns NULL if memory could not be allocated.</P
><P
><SPAN
CLASS="ERRORCODE"
>LWRES_R_SUCCESS</SPAN
>
is returned when
<TT
CLASS="FUNCTION"
>lwres_context_sendrecv()</TT
>
completes successfully.
<SPAN
CLASS="ERRORCODE"
>LWRES_R_IOERROR</SPAN
>
is returned if an I/O error occurs and
<SPAN
CLASS="ERRORCODE"
>LWRES_R_TIMEOUT</SPAN
>
is returned if
<TT
CLASS="FUNCTION"
>lwres_context_sendrecv()</TT
>
times out waiting for a response.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN130"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_conf_init</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>malloc</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>free</SPAN
>(3)</SPAN
>.</P
></DIV
></BODY
></HTML
>