Import initial strongswan 2.7.0 version into SVN.

1 files changed, 283 insertions, 0 deletions

diff --git a/lib/liblwres/man/lwres_context.docbook b/lib/liblwres/man/lwres_context.docbook
new file mode 100644
index 000000000..9cdfa7525
--- /dev/null
+++ b/lib/liblwres/man/lwres_context.docbook
@@ -0,0 +1,283 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<!--
+ - Copyright (C) 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.
+-->
+
+<!-- $Id: lwres_context.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
+
+<refentry>
+<refentryinfo>
+
+
+<date>Jun 30, 2000</date>
+</refentryinfo>
+<refmeta>
+<refentrytitle>lwres_context</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>BIND9</refmiscinfo>
+</refmeta>
+<refnamediv>
+<refname>lwres_context_create</refname>
+<refname>lwres_context_destroy</refname>
+<refname>lwres_context_nextserial</refname>
+<refname>lwres_context_initserial</refname>
+<refname>lwres_context_freemem</refname>
+<refname>lwres_context_allocmem</refname>
+<refname>lwres_context_sendrecv</refname>
+<refpurpose>lightweight resolver context management</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_context_create</function></funcdef>
+<paramdef>lwres_context_t **contextp</paramdef>
+<paramdef>void *arg</paramdef>
+<paramdef>lwres_malloc_t malloc_function</paramdef>
+<paramdef>lwres_free_t free_function</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+lwres_result_t
+<function>lwres_context_destroy</function></funcdef>
+<paramdef>lwres_context_t **contextp</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void
+<function>lwres_context_initserial</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>lwres_uint32_t serial</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+lwres_uint32_t
+<function>lwres_context_nextserial</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void
+<function>lwres_context_freemem</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>void *mem</paramdef>
+<paramdef>size_t len</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void
+<function>lwres_context_allocmem</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>size_t len</paramdef>
+</funcprototype>
+<funcprototype>
+<funcdef>
+void *
+<function>lwres_context_sendrecv</function></funcdef>
+<paramdef>lwres_context_t *ctx</paramdef>
+<paramdef>void *sendbase</paramdef>
+<paramdef>int sendlen</paramdef>
+<paramdef>void *recvbase</paramdef>
+<paramdef>int recvlen</paramdef>
+<paramdef>int *recvd_len</paramdef>
+</funcprototype>
+</funcsynopsis>
+</refsynopsisdiv>
+<refsect1>
+<title>DESCRIPTION</title>
+<para>
+<function>lwres_context_create()</function>
+creates a
+<type>lwres_context_t</type>
+structure for use in lightweight resolver operations.
+It holds a socket and other data needed for communicating
+with a resolver daemon.
+The new
+<type>lwres_context_t</type>
+is returned throught
+<parameter>contextp</parameter>,
+
+a pointer to a
+<type>lwres_context_t</type>
+pointer.  This 
+<type>lwres_context_t</type>
+pointer must initially be NULL, and is modified 
+to point to the newly created
+<type>lwres_context_t</type>.
+
+</para>
+<para>
+When the lightweight resolver needs to perform dynamic memory
+allocation, it will call
+<parameter>malloc_function</parameter>
+to allocate memory and
+<parameter>free_function</parameter>
+
+to free it.  If 
+<parameter>malloc_function</parameter>
+and
+<parameter>free_function</parameter>
+
+are NULL, memory is allocated using
+.Xr malloc 3
+and
+<citerefentry>
+<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
+</citerefentry>.
+
+It is not permitted to have a NULL
+<parameter>malloc_function</parameter>
+and a non-NULL
+<parameter>free_function</parameter>
+or vice versa.
+<parameter>arg</parameter>
+is passed as the first parameter to the memory
+allocation functions.  
+If
+<parameter>malloc_function</parameter>
+and
+<parameter>free_function</parameter>
+are NULL,
+<parameter>arg</parameter>
+
+is unused and should be passed as NULL.
+</para>
+<para>
+Once memory for the structure has been allocated,
+it is initialized using
+<citerefentry>
+<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
+</citerefentry>
+
+and returned via
+<parameter>*contextp</parameter>.
+
+</para>
+<para>
+<function>lwres_context_destroy()</function>
+destroys a 
+<type>lwres_context_t</type>,
+
+closing its socket.
+<parameter>contextp</parameter>
+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.
+</para>
+<para>
+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
+<function>lwres_context_initserial()</function>
+and
+<function>lwres_context_nextserial()</function>.
+<function>lwres_context_initserial()</function>
+sets the serial number for context
+<parameter>*ctx</parameter>
+to
+<parameter>serial</parameter>.
+
+<function>lwres_context_nextserial()</function>
+increments the serial number and returns the previous value.
+</para>
+<para>
+Memory for a lightweight resolver context is allocated and freed using
+<function>lwres_context_allocmem()</function>
+and
+<function>lwres_context_freemem()</function>.
+These use whatever allocations were defined when the context was
+created with
+<function>lwres_context_create()</function>.
+<function>lwres_context_allocmem()</function>
+allocates
+<parameter>len</parameter>
+bytes of memory and if successful returns a pointer to the allocated
+storage.
+<function>lwres_context_freemem()</function>
+frees
+<parameter>len</parameter>
+bytes of space starting at location
+<parameter>mem</parameter>.
+
+</para>
+<para>
+<function>lwres_context_sendrecv()</function>
+performs I/O for the context
+<parameter>ctx</parameter>.
+
+Data are read and written from the context's socket.
+It writes data from
+<parameter>sendbase</parameter>
+&mdash; typically a lightweight resolver query packet &mdash;
+and waits for a reply which is copied to the receive buffer at
+<parameter>recvbase</parameter>.
+
+The number of bytes that were written to this receive buffer is
+returned in
+<parameter>*recvd_len</parameter>.
+
+</para>
+</refsect1>
+<refsect1>
+<title>RETURN VALUES</title>
+<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>
+</refsect1>
+<refsect1>
+<title>SEE ALSO</title>
+<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>
+</refsect1>
+</refentry>