contrib/bind-9.2.4rc7/lib/lwres/man/lwres_gnba.3

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and 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: lwres_gnba.3,v 1.13.2.2 2004/03/15 04:45:03 marka Exp $
  17 .\"
  18 .TH "LWRES_GNBA" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free \- lightweight resolver getnamebyaddress message handling
  21 .SH SYNOPSIS
  22 \fB#include <lwres/lwres.h>
  23 .sp
  24 .na
  25 lwres_result_t
  26 lwres_gnbarequest_render(lwres_context_t *\fIctx\fB, lwres_gnbarequest_t *\fIreq\fB, lwres_lwpacket_t *\fIpkt\fB, lwres_buffer_t *\fIb\fB);
  27 .ad
  28 .sp
  29 .na
  30 lwres_result_t
  31 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
  32 .ad
  33 .sp
  34 .na
  35 lwres_result_t
  36 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
  37 .ad
  38 .sp
  39 .na
  40 lwres_result_t
  41 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp);
  42 .ad
  43 .sp
  44 .na
  45 void
  46 lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
  47 .ad
  48 .sp
  49 .na
  50 void
  51 lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
  52 .ad
  53 \fR
  54 .SH "DESCRIPTION"
  55 .PP
  56 These are low-level routines for creating and parsing
  57 lightweight resolver address-to-name lookup request and
  58 response messages.
  59 .PP
  60 There are four main functions for the getnamebyaddr opcode.
  61 One render function converts a getnamebyaddr request structure \(em
  62 \fBlwres_gnbarequest_t\fR \(em
  63 to the lightweight resolver's canonical format.
  64 It is complemented by a parse function that converts a packet in this
  65 canonical format to a getnamebyaddr request structure.
  66 Another render function converts the getnamebyaddr response structure \(em
  67 \fBlwres_gnbaresponse_t\fR
  68 to the canonical format.
  69 This is complemented by a parse function which converts a packet in
  70 canonical format to a getnamebyaddr response structure.
  71 .PP
  72 These structures are defined in
  73 \fIlwres/lwres.h\fR.
  74 They are shown below.
  75 .sp
  76 .nf
  77 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
  78
  79 typedef struct {
  80         lwres_uint32_t  flags;
  81         lwres_addr_t    addr;
  82 } lwres_gnbarequest_t;
  83
  84 typedef struct {
  85         lwres_uint32_t  flags;
  86         lwres_uint16_t  naliases;
  87         char           *realname;
  88         char          **aliases;
  89         lwres_uint16_t  realnamelen;
  90         lwres_uint16_t *aliaslen;
  91         void           *base;
  92         size_t          baselen;
  93 } lwres_gnbaresponse_t;
  94 .sp
  95 .fi
  96 .PP
  97 \fBlwres_gnbarequest_render()\fR
  98 uses resolver context
  99 ctx
 100 to convert getnamebyaddr request structure
 101 req
 102 to canonical format.
 103 The packet header structure
 104 pkt
 105 is initialised and transferred to
 106 buffer
 107 b.
 108 The contents of
 109 *req
 110 are then appended to the buffer in canonical format.
 111 \fBlwres_gnbaresponse_render()\fR
 112 performs the same task, except it converts a getnamebyaddr response structure
 113 \fBlwres_gnbaresponse_t\fR
 114 to the lightweight resolver's canonical format.
 115 .PP
 116 \fBlwres_gnbarequest_parse()\fR
 117 uses context
 118 ctx
 119 to convert the contents of packet
 120 pkt
 121 to a
 122 \fBlwres_gnbarequest_t\fR
 123 structure.
 124 Buffer
 125 b
 126 provides space to be used for storing this structure.
 127 When the function succeeds, the resulting
 128 \fBlwres_gnbarequest_t\fR
 129 is made available through
 130 *structp.
 131 \fBlwres_gnbaresponse_parse()\fR
 132 offers the same semantics as
 133 \fBlwres_gnbarequest_parse()\fR
 134 except it yields a
 135 \fBlwres_gnbaresponse_t\fR
 136 structure.
 137 .PP
 138 \fBlwres_gnbaresponse_free()\fR
 139 and
 140 \fBlwres_gnbarequest_free()\fR
 141 release the memory in resolver context
 142 ctx
 143 that was allocated to the
 144 \fBlwres_gnbaresponse_t\fR
 145 or
 146 \fBlwres_gnbarequest_t\fR
 147 structures referenced via
 148 structp.
 149 Any memory associated with ancillary buffers and strings for those
 150 structures is also discarded.
 151 .SH "RETURN VALUES"
 152 .PP
 153 The getnamebyaddr opcode functions
 154 \fBlwres_gnbarequest_render()\fR,
 155 \fBlwres_gnbaresponse_render()\fR
 156 \fBlwres_gnbarequest_parse()\fR
 157 and
 158 \fBlwres_gnbaresponse_parse()\fR
 159 all return
 160 LWRES_R_SUCCESS
 161 on success.
 162 They return
 163 LWRES_R_NOMEMORY
 164 if memory allocation fails.
 165 LWRES_R_UNEXPECTEDEND
 166 is returned if the available space in the buffer
 167 b
 168 is too small to accommodate the packet header or the
 169 \fBlwres_gnbarequest_t\fR
 170 and
 171 \fBlwres_gnbaresponse_t\fR
 172 structures.
 173 \fBlwres_gnbarequest_parse()\fR
 174 and
 175 \fBlwres_gnbaresponse_parse()\fR
 176 will return
 177 LWRES_R_UNEXPECTEDEND
 178 if the buffer is not empty after decoding the received packet.
 179 These functions will return
 180 LWRES_R_FAILURE
 181 if
 182 \fBpktflags\fR
 183 in the packet header structure
 184 \fBlwres_lwpacket_t\fR
 185 indicate that the packet is not a response to an earlier query.
 186 .SH "SEE ALSO"
 187 .PP
 188 \fBlwres_packet\fR(3).