diff options
Diffstat (limited to 'lib/lwres/man/lwres_gabn.3')
| -rw-r--r-- | lib/lwres/man/lwres_gabn.3 | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/lib/lwres/man/lwres_gabn.3 b/lib/lwres/man/lwres_gabn.3 new file mode 100644 index 0000000..5e9b070 --- /dev/null +++ b/lib/lwres/man/lwres_gabn.3 @@ -0,0 +1,217 @@ +.\" Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 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/. +.\" +.hy 0 +.ad l +'\" t +.\" Title: lwres_gabn +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 2007-06-18 +.\" Manual: BIND9 +.\" Source: ISC +.\" Language: English +.\" +.TH "LWRES_GABN" "3" "2007\-06\-18" "ISC" "BIND9" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.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" +.sp +.ft B +.nf +#include <lwres/lwres\&.h> +.fi +.ft +.HP \w'lwres_result_t\ lwres_gabnrequest_render('u +.BI "lwres_result_t lwres_gabnrequest_render(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" +.HP \w'lwres_result_t\ lwres_gabnresponse_render('u +.BI "lwres_result_t lwres_gabnresponse_render(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" +.HP \w'lwres_result_t\ lwres_gabnrequest_parse('u +.BI "lwres_result_t lwres_gabnrequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnrequest_t\ **" "structp" ");" +.HP \w'lwres_result_t\ lwres_gabnresponse_parse('u +.BI "lwres_result_t lwres_gabnresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnresponse_t\ **" "structp" ");" +.HP \w'void\ lwres_gabnresponse_free('u +.BI "void lwres_gabnresponse_free(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ **" "structp" ");" +.HP \w'void\ lwres_gabnrequest_free('u +.BI "void lwres_gabnrequest_free(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ **" "structp" ");" +.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 lightweight resolver\*(Aqs 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 +<lwres/lwres\&.h>\&. They are shown below\&. +.PP +.if n \{\ +.RS 4 +.\} +.nf +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +typedef struct { + uint32_t flags; + uint32_t addrtypes; + uint16_t namelen; + char *name; +} lwres_gabnrequest_t; +.fi +.if n \{\ +.RE +.\} +.PP +.if n \{\ +.RS 4 +.\} +.nf +typedef struct { + uint32_t flags; + uint16_t naliases; + uint16_t naddrs; + char *realname; + char **aliases; + uint16_t realnamelen; + uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.fi +.if n \{\ +.RE +.\} +.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\*(Aqs 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 +\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_gabnrequest_t\fR +and +\fBlwres_gabnresponse_t\fR +structures\&. +\fBlwres_gabnrequest_parse()\fR +and +\fBlwres_gabnresponse_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 +\fIpktflags\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 "AUTHOR" +.PP +\fBInternet Systems Consortium, Inc\&.\fR +.SH "COPYRIGHT" +.br +Copyright \(co 2000, 2001, 2004, 2005, 2007, 2014-2016, 2018, 2019 Internet Systems Consortium, Inc. ("ISC") +.br |