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

   1 .\" Copyright (C) 2004, 2005, 2007, 2014, 2015 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 .hy 0
  17 .ad l
  18 '\" t
  19 .\"     Title: lwres_gabn
  20 .\"    Author:
  21 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
  22 .\"      Date: 2007-06-18
  23 .\"    Manual: BIND9
  24 .\"    Source: ISC
  25 .\"  Language: English
  26 .\"
  27 .TH "LWRES_GABN" "3" "2007\-06\-18" "ISC" "BIND9"
  28 .\" -----------------------------------------------------------------
  29 .\" * Define some portability stuff
  30 .\" -----------------------------------------------------------------
  31 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  32 .\" http://bugs.debian.org/507673
  33 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35 .ie \n(.g .ds Aq \(aq
  36 .el       .ds Aq '
  37 .\" -----------------------------------------------------------------
  38 .\" * set default formatting
  39 .\" -----------------------------------------------------------------
  40 .\" disable hyphenation
  41 .nh
  42 .\" disable justification (adjust text to left margin only)
  43 .ad l
  44 .\" -----------------------------------------------------------------
  45 .\" * MAIN CONTENT STARTS HERE *
  46 .\" -----------------------------------------------------------------
  47 .SH "NAME"
  48 lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling
  49 .SH "SYNOPSIS"
  50 .sp
  51 .ft B
  52 .nf
  53 #include <lwres/lwres\&.h>
  54 .fi
  55 .ft
  56 .HP \w'lwres_result_t\ lwres_gabnrequest_render('u
  57 .BI "lwres_result_t lwres_gabnrequest_render(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
  58 .HP \w'lwres_result_t\ lwres_gabnresponse_render('u
  59 .BI "lwres_result_t lwres_gabnresponse_render(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");"
  60 .HP \w'lwres_result_t\ lwres_gabnrequest_parse('u
  61 .BI "lwres_result_t lwres_gabnrequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnrequest_t\ **" "structp" ");"
  62 .HP \w'lwres_result_t\ lwres_gabnresponse_parse('u
  63 .BI "lwres_result_t lwres_gabnresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnresponse_t\ **" "structp" ");"
  64 .HP \w'void\ lwres_gabnresponse_free('u
  65 .BI "void lwres_gabnresponse_free(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ **" "structp" ");"
  66 .HP \w'void\ lwres_gabnrequest_free('u
  67 .BI "void lwres_gabnrequest_free(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ **" "structp" ");"
  68 .SH "DESCRIPTION"
  69 .PP
  70 These are low\-level routines for creating and parsing lightweight resolver name\-to\-address lookup request and response messages\&.
  71 .PP
  72 There are four main functions for the getaddrbyname opcode\&. One render function converts a getaddrbyname request structure \(em
  73 \fBlwres_gabnrequest_t\fR
  74 \(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
  75 \fBlwres_gabnresponse_t\fR
  76 \(em to the canonical format\&. This is complemented by a parse function which converts a packet in canonical format to a getaddrbyname response structure\&.
  77 .PP
  78 These structures are defined in
  79 <lwres/lwres\&.h>\&. They are shown below\&.
  80 .PP
  81 .if n \{\
  82 .RS 4
  83 .\}
  84 .nf
  85 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
  86 .fi
  87 .if n \{\
  88 .RE
  89 .\}
  90 .PP
  91 .if n \{\
  92 .RS 4
  93 .\}
  94 .nf
  95 typedef struct lwres_addr lwres_addr_t;
  96 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
  97 .fi
  98 .if n \{\
  99 .RE
 100 .\}
 101 .PP
 102 .if n \{\
 103 .RS 4
 104 .\}
 105 .nf
 106 typedef struct {
 107         lwres_uint32_t  flags;
 108         lwres_uint32_t  addrtypes;
 109         lwres_uint16_t  namelen;
 110         char           *name;
 111 } lwres_gabnrequest_t;
 112 .fi
 113 .if n \{\
 114 .RE
 115 .\}
 116 .PP
 117 .if n \{\
 118 .RS 4
 119 .\}
 120 .nf
 121 typedef struct {
 122         lwres_uint32_t          flags;
 123         lwres_uint16_t          naliases;
 124         lwres_uint16_t          naddrs;
 125         char                   *realname;
 126         char                  **aliases;
 127         lwres_uint16_t          realnamelen;
 128         lwres_uint16_t         *aliaslen;
 129         lwres_addrlist_t        addrs;
 130         void                   *base;
 131         size_t                  baselen;
 132 } lwres_gabnresponse_t;
 133 .fi
 134 .if n \{\
 135 .RE
 136 .\}
 137 .PP
 138 \fBlwres_gabnrequest_render()\fR
 139 uses resolver context
 140 \fIctx\fR
 141 to convert getaddrbyname request structure
 142 \fIreq\fR
 143 to canonical format\&. The packet header structure
 144 \fIpkt\fR
 145 is initialised and transferred to buffer
 146 \fIb\fR\&. The contents of
 147 \fI*req\fR
 148 are then appended to the buffer in canonical format\&.
 149 \fBlwres_gabnresponse_render()\fR
 150 performs the same task, except it converts a getaddrbyname response structure
 151 \fBlwres_gabnresponse_t\fR
 152 to the lightweight resolver\*(Aqs canonical format\&.
 153 .PP
 154 \fBlwres_gabnrequest_parse()\fR
 155 uses context
 156 \fIctx\fR
 157 to convert the contents of packet
 158 \fIpkt\fR
 159 to a
 160 \fBlwres_gabnrequest_t\fR
 161 structure\&. Buffer
 162 \fIb\fR
 163 provides space to be used for storing this structure\&. When the function succeeds, the resulting
 164 \fBlwres_gabnrequest_t\fR
 165 is made available through
 166 \fI*structp\fR\&.
 167 \fBlwres_gabnresponse_parse()\fR
 168 offers the same semantics as
 169 \fBlwres_gabnrequest_parse()\fR
 170 except it yields a
 171 \fBlwres_gabnresponse_t\fR
 172 structure\&.
 173 .PP
 174 \fBlwres_gabnresponse_free()\fR
 175 and
 176 \fBlwres_gabnrequest_free()\fR
 177 release the memory in resolver context
 178 \fIctx\fR
 179 that was allocated to the
 180 \fBlwres_gabnresponse_t\fR
 181 or
 182 \fBlwres_gabnrequest_t\fR
 183 structures referenced via
 184 \fIstructp\fR\&. Any memory associated with ancillary buffers and strings for those structures is also discarded\&.
 185 .SH "RETURN VALUES"
 186 .PP
 187 The getaddrbyname opcode functions
 188 \fBlwres_gabnrequest_render()\fR,
 189 \fBlwres_gabnresponse_render()\fR\fBlwres_gabnrequest_parse()\fR
 190 and
 191 \fBlwres_gabnresponse_parse()\fR
 192 all return
 193 \fBLWRES_R_SUCCESS\fR
 194 on success\&. They return
 195 \fBLWRES_R_NOMEMORY\fR
 196 if memory allocation fails\&.
 197 \fBLWRES_R_UNEXPECTEDEND\fR
 198 is returned if the available space in the buffer
 199 \fIb\fR
 200 is too small to accommodate the packet header or the
 201 \fBlwres_gabnrequest_t\fR
 202 and
 203 \fBlwres_gabnresponse_t\fR
 204 structures\&.
 205 \fBlwres_gabnrequest_parse()\fR
 206 and
 207 \fBlwres_gabnresponse_parse()\fR
 208 will return
 209 \fBLWRES_R_UNEXPECTEDEND\fR
 210 if the buffer is not empty after decoding the received packet\&. These functions will return
 211 \fBLWRES_R_FAILURE\fR
 212 if
 213 \fIpktflags\fR
 214 in the packet header structure
 215 \fBlwres_lwpacket_t\fR
 216 indicate that the packet is not a response to an earlier query\&.
 217 .SH "SEE ALSO"
 218 .PP
 219 \fBlwres_packet\fR(3)
 220 .SH "AUTHOR"
 221 .PP
 222 \fBInternet Systems Consortium, Inc\&.\fR
 223 .SH "COPYRIGHT"
 224 .br
 225 Copyright \(co 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
 226 .br
 227 Copyright \(co 2000, 2001 Internet Software Consortium.
 228 .br