+++ /dev/null
-.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
-.\" 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 ISC DISCLAIMS ALL WARRANTIES WITH
-.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-.\" AND FITNESS. IN NO EVENT SHALL ISC 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_noop.3,v 1.28 2007/01/30 00:24:59 marka Exp $
-.\"
-.hy 0
-.ad l
-.\" Title: lwres_noop
-.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
-.\" Date: Jun 30, 2000
-.\" Manual: BIND9
-.\" Source: BIND9
-.\"
-.TH "LWRES_NOOP" "3" "Jun 30, 2000" "BIND9" "BIND9"
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.SH "NAME"
-lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free \- lightweight resolver no\-op message handling
-.SH "SYNOPSIS"
-.nf
-#include <lwres/lwres.h>
-.fi
-.HP 40
-.BI "lwres_result_t lwres_nooprequest_render(lwres_context_t\ *" "ctx" ", lwres_nooprequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
-.HP 41
-.BI "lwres_result_t lwres_noopresponse_render(lwres_context_t\ *" "ctx" ", lwres_noopresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
-.HP 39
-.BI "lwres_result_t lwres_nooprequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_nooprequest_t\ **" "structp" ");"
-.HP 40
-.BI "lwres_result_t lwres_noopresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_noopresponse_t\ **" "structp" ");"
-.HP 29
-.BI "void lwres_noopresponse_free(lwres_context_t\ *" "ctx" ", lwres_noopresponse_t\ **" "structp" ");"
-.HP 28
-.BI "void lwres_nooprequest_free(lwres_context_t\ *" "ctx" ", lwres_nooprequest_t\ **" "structp" ");"
-.SH "DESCRIPTION"
-.PP
-These are low\-level routines for creating and parsing lightweight resolver no\-op request and response messages.
-.PP
-The no\-op message is analogous to a
-\fBping\fR
-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.
-.PP
-There are four main functions for the no\-op opcode. One render function converts a no\-op request structure \(em
-\fBlwres_nooprequest_t\fR
-\(em to the lighweight 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 \(em
-\fBlwres_noopresponse_t\fR
-to the canonical format. This is complemented by a parse function which converts a packet in canonical format to a no\-op response structure.
-.PP
-These structures are defined in
-\fIlwres/lwres.h\fR. They are shown below.
-.PP
-.RS 4
-.nf
-#define LWRES_OPCODE_NOOP 0x00000000U
-.fi
-.RE
-.sp
-.PP
-.RS 4
-.nf
-typedef struct {
- lwres_uint16_t datalength;
- unsigned char *data;
-} lwres_nooprequest_t;
-.fi
-.RE
-.sp
-.PP
-.RS 4
-.nf
-typedef struct {
- lwres_uint16_t datalength;
- unsigned char *data;
-} lwres_noopresponse_t;
-.fi
-.RE
-.sp
-.PP
-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.
-.PP
-\fBlwres_nooprequest_render()\fR
-uses resolver context
-\fIctx\fR
-to convert no\-op request structure
-\fIreq\fR
-to canonical format. The packet header structure
-\fIpkt\fR
-is initialised and transferred to buffer
-\fIb\fR. The contents of
-\fI*req\fR
-are then appended to the buffer in canonical format.
-\fBlwres_noopresponse_render()\fR
-performs the same task, except it converts a no\-op response structure
-\fBlwres_noopresponse_t\fR
-to the lightweight resolver's canonical format.
-.PP
-\fBlwres_nooprequest_parse()\fR
-uses context
-\fIctx\fR
-to convert the contents of packet
-\fIpkt\fR
-to a
-\fBlwres_nooprequest_t\fR
-structure. Buffer
-\fIb\fR
-provides space to be used for storing this structure. When the function succeeds, the resulting
-\fBlwres_nooprequest_t\fR
-is made available through
-\fI*structp\fR.
-\fBlwres_noopresponse_parse()\fR
-offers the same semantics as
-\fBlwres_nooprequest_parse()\fR
-except it yields a
-\fBlwres_noopresponse_t\fR
-structure.
-.PP
-\fBlwres_noopresponse_free()\fR
-and
-\fBlwres_nooprequest_free()\fR
-release the memory in resolver context
-\fIctx\fR
-that was allocated to the
-\fBlwres_noopresponse_t\fR
-or
-\fBlwres_nooprequest_t\fR
-structures referenced via
-\fIstructp\fR.
-.SH "RETURN VALUES"
-.PP
-The no\-op opcode functions
-\fBlwres_nooprequest_render()\fR,
-\fBlwres_noopresponse_render()\fR
-\fBlwres_nooprequest_parse()\fR
-and
-\fBlwres_noopresponse_parse()\fR
-all return
-\fBLWRES_R_SUCCESS\fR
-on success. They return
-\fBLWRES_R_NOMEMORY\fR
-if memory allocation fails.
-\fBLWRES_R_UNEXPECTEDEND\fR
-is returned if the available space in the buffer
-\fIb\fR
-is too small to accommodate the packet header or the
-\fBlwres_nooprequest_t\fR
-and
-\fBlwres_noopresponse_t\fR
-structures.
-\fBlwres_nooprequest_parse()\fR
-and
-\fBlwres_noopresponse_parse()\fR
-will return
-\fBLWRES_R_UNEXPECTEDEND\fR
-if the buffer is not empty after decoding the received packet. These functions will return
-\fBLWRES_R_FAILURE\fR
-if
-\fBpktflags\fR
-in the packet header structure
-\fBlwres_lwpacket_t\fR
-indicate that the packet is not a response to an earlier query.
-.SH "SEE ALSO"
-.PP
-\fBlwres_packet\fR(3)
-.SH "COPYRIGHT"
-Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
-.br
-Copyright \(co 2000, 2001 Internet Software Consortium.
-.br
git.samba.org / tridge / bind9.git / blobdiff