lib/liblwres/man/lwres_gabn.3

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