diff options
Diffstat (limited to 'lib/liblwres/man/lwres_gabn.3')
| -rw-r--r-- | lib/liblwres/man/lwres_gabn.3 | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_gabn.3 b/lib/liblwres/man/lwres_gabn.3 new file mode 100644 index 000000000..79a22c14f --- /dev/null +++ b/lib/liblwres/man/lwres_gabn.3 @@ -0,0 +1,193 @@ +.\" +.\" 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. +.\" +.TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" "" +.SH NAME +lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling +.SH SYNOPSIS +\fB#include <lwres/lwres.h> +.sp +.na +lwres_result_t +lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); +.ad +.sp +.na +lwres_result_t +lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); +.ad +.sp +.na +lwres_result_t +lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp); +.ad +.sp +.na +lwres_result_t +lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp); +.ad +.sp +.na +void +lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); +.ad +.sp +.na +void +lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); +.ad +\fR.SH "DESCRIPTION" +.PP +These are low-level routines for creating and parsing +lightweight resolver name-to-address lookup request and +response messages. +.PP +There are four main functions for the getaddrbyname opcode. +One render function converts a getaddrbyname request structure \(em +\fBlwres_gabnrequest_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 getaddrbyname request structure. +Another render function converts the getaddrbyname response structure \(em +\fBlwres_gabnresponse_t\fR \(em +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getaddrbyname response structure. +.PP +These structures are defined in +\fI<lwres/lwres.h>\fR. +They are shown below. +.sp +.nf +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U + +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint32_t addrtypes; + lwres_uint16_t namelen; + char *name; +} lwres_gabnrequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.sp +.fi +.PP +\fBlwres_gabnrequest_render()\fR +uses resolver context +\fIctx\fR +to convert getaddrbyname 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_gabnresponse_render()\fR +performs the same task, except it converts a getaddrbyname response structure +\fBlwres_gabnresponse_t\fR +to the lightweight resolver's canonical format. +.PP +\fBlwres_gabnrequest_parse()\fR +uses context +\fIctx\fR +to convert the contents of packet +\fIpkt\fR +to a +\fBlwres_gabnrequest_t\fR +structure. +Buffer +\fIb\fR +provides space to be used for storing this structure. +When the function succeeds, the resulting +\fBlwres_gabnrequest_t\fR +is made available through +\fI*structp\fR. +\fBlwres_gabnresponse_parse()\fR +offers the same semantics as +\fBlwres_gabnrequest_parse()\fR +except it yields a +\fBlwres_gabnresponse_t\fR +structure. +.PP +\fBlwres_gabnresponse_free()\fR +and +\fBlwres_gabnrequest_free()\fR +release the memory in resolver context +\fIctx\fR +that was allocated to the +\fBlwres_gabnresponse_t\fR +or +\fBlwres_gabnrequest_t\fR +structures referenced via +\fIstructp\fR. +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +.SH "RETURN VALUES" +.PP +The getaddrbyname opcode functions +\fBlwres_gabnrequest_render()\fR, +\fBlwres_gabnresponse_render()\fR +\fBlwres_gabnrequest_parse()\fR +and +\fBlwres_gabnresponse_parse()\fR +all return +LWRES_R_SUCCESS +on success. +They return +LWRES_R_NOMEMORY +if memory allocation fails. +LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +\fIb\fR +is too small to accommodate the packet header or the +\fBlwres_gabnrequest_t\fR +and +\fBlwres_gabnresponse_t\fR +structures. +\fBlwres_gabnrequest_parse()\fR +and +\fBlwres_gabnresponse_parse()\fR +will return +LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +LWRES_R_FAILURE +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) |