summaryrefslogtreecommitdiffstats
path: root/lib/lwres/man/lwres_noop.docbook
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 18:37:14 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-05 18:37:14 +0000
commitea648e70a989cca190cd7403fe892fd2dcc290b4 (patch)
treee2b6b1c647da68b0d4d66082835e256eb30970e8 /lib/lwres/man/lwres_noop.docbook
parentInitial commit. (diff)
downloadbind9-upstream.tar.xz
bind9-upstream.zip
Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'lib/lwres/man/lwres_noop.docbook')
-rw-r--r--lib/lwres/man/lwres_noop.docbook249
1 files changed, 249 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_noop.docbook b/lib/lwres/man/lwres_noop.docbook
new file mode 100644
index 0000000..64ab392
--- /dev/null
+++ b/lib/lwres/man/lwres_noop.docbook
@@ -0,0 +1,249 @@
+<!DOCTYPE book [
+<!ENTITY mdash "&#8212;">]>
+<!--
+ - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
+ <info>
+ <date>2007-06-18</date>
+ </info>
+ <refentryinfo>
+ <corpname>ISC</corpname>
+ <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>lwres_noop</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo>BIND9</refmiscinfo>
+ </refmeta>
+
+ <docinfo>
+ <copyright>
+ <year>2000</year>
+ <year>2001</year>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2007</year>
+ <year>2014</year>
+ <year>2015</year>
+ <year>2016</year>
+ <year>2018</year>
+ <year>2019</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+ </copyright>
+ </docinfo>
+
+ <refnamediv>
+ <refname>lwres_nooprequest_render</refname>
+ <refname>lwres_noopresponse_render</refname>
+ <refname>lwres_nooprequest_parse</refname>
+ <refname>lwres_noopresponse_parse</refname>
+ <refname>lwres_noopresponse_free</refname>
+ <refname>lwres_nooprequest_free</refname>
+ <refpurpose>lightweight resolver no-op message handling</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+<funcsynopsisinfo>
+#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_nooprequest_render</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_noopresponse_render</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_nooprequest_parse</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+lwres_result_t
+<function>lwres_noopresponse_parse</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
+ <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
+ <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+void
+<function>lwres_noopresponse_free</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
+ </funcprototype>
+<funcprototype>
+ <funcdef>
+void
+<function>lwres_nooprequest_free</function></funcdef>
+ <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
+ <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+ </refsynopsisdiv>
+ <refsection><info><title>DESCRIPTION</title></info>
+
+ <para>
+ These are low-level routines for creating and parsing
+ lightweight resolver no-op request and response messages.
+ </para>
+ <para>
+ The no-op message is analogous to a <command>ping</command>
+ packet:
+ a packet is sent to the resolver daemon and is simply echoed back.
+ The opcode is intended to allow a client to determine if the server is
+ operational or not.
+ </para>
+ <para>
+ There are four main functions for the no-op opcode.
+ One render function converts a no-op request structure &mdash;
+ <type>lwres_nooprequest_t</type> &mdash;
+ to the lightweight resolver's canonical format.
+ It is complemented by a parse function that converts a packet in this
+ canonical format to a no-op request structure.
+ Another render function converts the no-op response structure &mdash;
+ <type>lwres_noopresponse_t</type>
+ to the canonical format.
+ This is complemented by a parse function which converts a packet in
+ canonical format to a no-op response structure.
+ </para>
+ <para>
+ These structures are defined in
+ <filename>lwres/lwres.h</filename>.
+
+ They are shown below.
+ </para>
+ <para><programlisting>
+#define LWRES_OPCODE_NOOP 0x00000000U
+</programlisting>
+ </para>
+ <para><programlisting>
+typedef struct {
+ uint16_t datalength;
+ unsigned char *data;
+} lwres_nooprequest_t;
+</programlisting>
+ </para>
+ <para><programlisting>
+typedef struct {
+ uint16_t datalength;
+ unsigned char *data;
+} lwres_noopresponse_t;
+</programlisting>
+ </para>
+ <para>
+ Although the structures have different types, they are identical.
+ This is because the no-op opcode simply echos whatever data was sent:
+ the response is therefore identical to the request.
+ </para>
+
+ <para><function>lwres_nooprequest_render()</function>
+ uses resolver context <parameter>ctx</parameter> to convert
+ no-op request structure <parameter>req</parameter> to canonical
+ format. The packet header structure <parameter>pkt</parameter>
+ is initialised and transferred to buffer
+ <parameter>b</parameter>. The contents of
+ <parameter>*req</parameter> are then appended to the buffer in
+ canonical format.
+ <function>lwres_noopresponse_render()</function> performs the
+ same task, except it converts a no-op response structure
+ <type>lwres_noopresponse_t</type> to the lightweight resolver's
+ canonical format.
+ </para>
+
+ <para><function>lwres_nooprequest_parse()</function>
+ uses context <parameter>ctx</parameter> to convert the contents
+ of packet <parameter>pkt</parameter> to a
+ <type>lwres_nooprequest_t</type> structure. Buffer
+ <parameter>b</parameter> provides space to be used for storing
+ this structure. When the function succeeds, the resulting
+ <type>lwres_nooprequest_t</type> is made available through
+ <parameter>*structp</parameter>.
+ <function>lwres_noopresponse_parse()</function> offers the same
+ semantics as <function>lwres_nooprequest_parse()</function>
+ except it yields a <type>lwres_noopresponse_t</type> structure.
+ </para>
+
+ <para><function>lwres_noopresponse_free()</function>
+ and <function>lwres_nooprequest_free()</function> release the
+ memory in resolver context <parameter>ctx</parameter> that was
+ allocated to the <type>lwres_noopresponse_t</type> or
+ <type>lwres_nooprequest_t</type> structures referenced via
+ <parameter>structp</parameter>.
+ </para>
+
+ </refsection>
+ <refsection><info><title>RETURN VALUES</title></info>
+
+ <para>
+ The no-op opcode functions
+ <function>lwres_nooprequest_render()</function>,
+
+ <function>lwres_noopresponse_render()</function>
+ <function>lwres_nooprequest_parse()</function>
+ and
+ <function>lwres_noopresponse_parse()</function>
+ all return
+ <errorcode>LWRES_R_SUCCESS</errorcode>
+ on success.
+ They return
+ <errorcode>LWRES_R_NOMEMORY</errorcode>
+ if memory allocation fails.
+ <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+ is returned if the available space in the buffer
+ <parameter>b</parameter>
+ is too small to accommodate the packet header or the
+ <type>lwres_nooprequest_t</type>
+ and
+ <type>lwres_noopresponse_t</type>
+ structures.
+ <function>lwres_nooprequest_parse()</function>
+ and
+ <function>lwres_noopresponse_parse()</function>
+ will return
+ <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
+ if the buffer is not empty after decoding the received packet.
+ These functions will return
+ <errorcode>LWRES_R_FAILURE</errorcode>
+ if
+ <constant>pktflags</constant>
+ in the packet header structure
+ <type>lwres_lwpacket_t</type>
+ indicate that the packet is not a response to an earlier query.
+ </para>
+ </refsection>
+ <refsection><info><title>SEE ALSO</title></info>
+
+ <para><citerefentry>
+ <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsection>
+</refentry>