diff options
Diffstat (limited to 'lib/lwres/man/lwres_noop.3')
| -rw-r--r-- | lib/lwres/man/lwres_noop.3 | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_noop.3 b/lib/lwres/man/lwres_noop.3 new file mode 100644 index 0000000..0e4ed71 --- /dev/null +++ b/lib/lwres/man/lwres_noop.3 @@ -0,0 +1,183 @@ +.\" 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 |