/contrib/bind9/lib/lwres/man/lwres_gabn.3

  1.\" Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  2.\" Copyright (C) 2000, 2001 Internet Software Consortium.
  3.\" 
  4.\" Permission to use, copy, modify, and/or distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\" 
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  9.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 10.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 11.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 12.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 13.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 14.\" PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.\" $Id$
 17.\"
 18.hy 0
 19.ad l
 20.\"     Title: lwres_gabn
 21.\"    Author: 
 22.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
 23.\"      Date: Jun 30, 2000
 24.\"    Manual: BIND9
 25.\"    Source: BIND9
 26.\"
 27.TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" "BIND9"
 28.\" disable hyphenation
 29.nh
 30.\" disable justification (adjust text to left margin only)
 31.ad l
 32.SH "NAME"
 33lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling
 34.SH "SYNOPSIS"
 35.nf
 36#include <lwres/lwres.h>
 37.fi
 38.HP 40
 39.BI "lwres_result_t lwres_gabnrequest_render(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
 40.HP 41
 41.BI "lwres_result_t lwres_gabnresponse_render(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
 42.HP 39
 43.BI "lwres_result_t lwres_gabnrequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnrequest_t\ **" "structp" ");"
 44.HP 40
 45.BI "lwres_result_t lwres_gabnresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnresponse_t\ **" "structp" ");"
 46.HP 29
 47.BI "void lwres_gabnresponse_free(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ **" "structp" ");"
 48.HP 28
 49.BI "void lwres_gabnrequest_free(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ **" "structp" ");"
 50.SH "DESCRIPTION"
 51.PP
 52These are low\-level routines for creating and parsing lightweight resolver name\-to\-address lookup request and response messages.
 53.PP
 54There are four main functions for the getaddrbyname opcode. One render function converts a getaddrbyname request structure \(em
 55\fBlwres_gabnrequest_t\fR
 56\(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
 57\fBlwres_gabnresponse_t\fR
 58\(em to the canonical format. This is complemented by a parse function which converts a packet in canonical format to a getaddrbyname response structure.
 59.PP
 60These structures are defined in
 61\fI<lwres/lwres.h>\fR. They are shown below.
 62.PP
 63.RS 4
 64.nf
 65#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 66.fi
 67.RE
 68.sp
 69.PP
 70.RS 4
 71.nf
 72typedef struct lwres_addr lwres_addr_t;
 73typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 74.fi
 75.RE
 76.sp
 77.PP
 78.RS 4
 79.nf
 80typedef struct {
 81        lwres_uint32_t  flags;
 82        lwres_uint32_t  addrtypes;
 83        lwres_uint16_t  namelen;
 84        char           *name;
 85} lwres_gabnrequest_t;
 86.fi
 87.RE
 88.sp
 89.PP
 90.RS 4
 91.nf
 92typedef struct {
 93        lwres_uint32_t          flags;
 94        lwres_uint16_t          naliases;
 95        lwres_uint16_t          naddrs;
 96        char                   *realname;
 97        char                  **aliases;
 98        lwres_uint16_t          realnamelen;
 99        lwres_uint16_t         *aliaslen;
100        lwres_addrlist_t        addrs;
101        void                   *base;
102        size_t                  baselen;
103} lwres_gabnresponse_t;
104.fi
105.RE
106.sp
107.PP
108\fBlwres_gabnrequest_render()\fR
109uses resolver context
110\fIctx\fR
111to convert getaddrbyname request structure
112\fIreq\fR
113to canonical format. The packet header structure
114\fIpkt\fR
115is initialised and transferred to buffer
116\fIb\fR. The contents of
117\fI*req\fR
118are then appended to the buffer in canonical format.
119\fBlwres_gabnresponse_render()\fR
120performs the same task, except it converts a getaddrbyname response structure
121\fBlwres_gabnresponse_t\fR
122to the lightweight resolver's canonical format.
123.PP
124\fBlwres_gabnrequest_parse()\fR
125uses context
126\fIctx\fR
127to convert the contents of packet
128\fIpkt\fR
129to a
130\fBlwres_gabnrequest_t\fR
131structure. Buffer
132\fIb\fR
133provides space to be used for storing this structure. When the function succeeds, the resulting
134\fBlwres_gabnrequest_t\fR
135is made available through
136\fI*structp\fR.
137\fBlwres_gabnresponse_parse()\fR
138offers the same semantics as
139\fBlwres_gabnrequest_parse()\fR
140except it yields a
141\fBlwres_gabnresponse_t\fR
142structure.
143.PP
144\fBlwres_gabnresponse_free()\fR
145and
146\fBlwres_gabnrequest_free()\fR
147release the memory in resolver context
148\fIctx\fR
149that was allocated to the
150\fBlwres_gabnresponse_t\fR
151or
152\fBlwres_gabnrequest_t\fR
153structures referenced via
154\fIstructp\fR. Any memory associated with ancillary buffers and strings for those structures is also discarded.
155.SH "RETURN VALUES"
156.PP
157The getaddrbyname opcode functions
158\fBlwres_gabnrequest_render()\fR,
159\fBlwres_gabnresponse_render()\fR
160\fBlwres_gabnrequest_parse()\fR
161and
162\fBlwres_gabnresponse_parse()\fR
163all return
164\fBLWRES_R_SUCCESS\fR
165on success. They return
166\fBLWRES_R_NOMEMORY\fR
167if memory allocation fails.
168\fBLWRES_R_UNEXPECTEDEND\fR
169is returned if the available space in the buffer
170\fIb\fR
171is too small to accommodate the packet header or the
172\fBlwres_gabnrequest_t\fR
173and
174\fBlwres_gabnresponse_t\fR
175structures.
176\fBlwres_gabnrequest_parse()\fR
177and
178\fBlwres_gabnresponse_parse()\fR
179will return
180\fBLWRES_R_UNEXPECTEDEND\fR
181if the buffer is not empty after decoding the received packet. These functions will return
182\fBLWRES_R_FAILURE\fR
183if
184pktflags
185in the packet header structure
186\fBlwres_lwpacket_t\fR
187indicate that the packet is not a response to an earlier query.
188.SH "SEE ALSO"
189.PP
190\fBlwres_packet\fR(3)
191.SH "COPYRIGHT"
192Copyright \(co 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
193.br
194Copyright \(co 2000, 2001 Internet Software Consortium.
195.br