contrib/bind-9.3/lib/lwres/man/lwres_gnba.3

   1 .\" Copyright (C) 2004, 2005 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.1.8.5 2005/10/13 02:33:53 marka Exp $
  17 .\"
  18 .hy 0
  19 .ad l
  20 .\" ** You probably do not want to edit this file directly **
  21 .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
  22 .\" Instead of manually editing it, you probably should edit the DocBook XML
  23 .\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
  24 .TH "LWRES_GNBA" "3" "Jun 30, 2000" "BIND9" "BIND9"
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .SH "NAME"
  30 lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free \- lightweight resolver getnamebyaddress message handling
  31 .SH "SYNOPSIS"
  32 .nf
  33 #include <lwres/lwres.h>
  34 .fi
  35 .HP 40
  36 \fBlwres_result_t\ \fBlwres_gnbarequest_render\fR\fR\fB(\fR\fBlwres_context_t\ *\fR\fB\fIctx\fR\fR\fB, \fR\fBlwres_gnbarequest_t\ *\fR\fB\fIreq\fR\fR\fB, \fR\fBlwres_lwpacket_t\ *\fR\fB\fIpkt\fR\fR\fB, \fR\fBlwres_buffer_t\ *\fR\fB\fIb\fR\fR\fB);\fR
  37 .HP 41
  38 \fBlwres_result_t\ \fBlwres_gnbaresponse_render\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gnbaresponse_t\ *req\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB);\fR
  39 .HP 39
  40 \fBlwres_result_t\ \fBlwres_gnbarequest_parse\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_gnbarequest_t\ **structp\fR\fB);\fR
  41 .HP 40
  42 \fBlwres_result_t\ \fBlwres_gnbaresponse_parse\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_buffer_t\ *b\fR\fB, \fR\fBlwres_lwpacket_t\ *pkt\fR\fB, \fR\fBlwres_gnbaresponse_t\ **structp\fR\fB);\fR
  43 .HP 29
  44 \fBvoid\ \fBlwres_gnbaresponse_free\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gnbaresponse_t\ **structp\fR\fB);\fR
  45 .HP 28
  46 \fBvoid\ \fBlwres_gnbarequest_free\fR\fR\fB(\fR\fBlwres_context_t\ *ctx\fR\fB, \fR\fBlwres_gnbarequest_t\ **structp\fR\fB);\fR
  47 .SH "DESCRIPTION"
  48 .PP
  49 These are low\-level routines for creating and parsing lightweight resolver address\-to\-name lookup request and response messages.
  50 .PP
  51 There are four main functions for the getnamebyaddr opcode. One render function converts a getnamebyaddr request structure \(em
  52 \fBlwres_gnbarequest_t\fR
  53 \(em to the lightweight resolver's canonical format. It is complemented by a parse function that converts a packet in this canonical format to a getnamebyaddr request structure. Another render function converts the getnamebyaddr response structure \(em
  54 \fBlwres_gnbaresponse_t\fR
  55 to the canonical format. This is complemented by a parse function which converts a packet in canonical format to a getnamebyaddr response structure.
  56 .PP
  57 These structures are defined in
  58 \fIlwres/lwres.h\fR. They are shown below.
  59 .sp
  60 .nf
  61 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
  62 typedef struct {
  63         lwres_uint32_t  flags;
  64         lwres_addr_t    addr;
  65 } lwres_gnbarequest_t;
  66 typedef struct {
  67         lwres_uint32_t  flags;
  68         lwres_uint16_t  naliases;
  69         char           *realname;
  70         char          **aliases;
  71         lwres_uint16_t  realnamelen;
  72         lwres_uint16_t *aliaslen;
  73         void           *base;
  74         size_t          baselen;
  75 } lwres_gnbaresponse_t;
  76 .fi
  77 .sp
  78 .PP
  79 \fBlwres_gnbarequest_render()\fR
  80 uses resolver context
  81 \fIctx\fR
  82 to convert getnamebyaddr request structure
  83 \fIreq\fR
  84 to canonical format. The packet header structure
  85 \fIpkt\fR
  86 is initialised and transferred to buffer
  87 \fIb\fR. The contents of
  88 \fI*req\fR
  89 are then appended to the buffer in canonical format.
  90 \fBlwres_gnbaresponse_render()\fR
  91 performs the same task, except it converts a getnamebyaddr response structure
  92 \fBlwres_gnbaresponse_t\fR
  93 to the lightweight resolver's canonical format.
  94 .PP
  95 \fBlwres_gnbarequest_parse()\fR
  96 uses context
  97 \fIctx\fR
  98 to convert the contents of packet
  99 \fIpkt\fR
 100 to a
 101 \fBlwres_gnbarequest_t\fR
 102 structure. Buffer
 103 \fIb\fR
 104 provides space to be used for storing this structure. When the function succeeds, the resulting
 105 \fBlwres_gnbarequest_t\fR
 106 is made available through
 107 \fI*structp\fR.
 108 \fBlwres_gnbaresponse_parse()\fR
 109 offers the same semantics as
 110 \fBlwres_gnbarequest_parse()\fR
 111 except it yields a
 112 \fBlwres_gnbaresponse_t\fR
 113 structure.
 114 .PP
 115 \fBlwres_gnbaresponse_free()\fR
 116 and
 117 \fBlwres_gnbarequest_free()\fR
 118 release the memory in resolver context
 119 \fIctx\fR
 120 that was allocated to the
 121 \fBlwres_gnbaresponse_t\fR
 122 or
 123 \fBlwres_gnbarequest_t\fR
 124 structures referenced via
 125 \fIstructp\fR. Any memory associated with ancillary buffers and strings for those structures is also discarded.
 126 .SH "RETURN VALUES"
 127 .PP
 128 The getnamebyaddr opcode functions
 129 \fBlwres_gnbarequest_render()\fR,
 130 \fBlwres_gnbaresponse_render()\fR\fBlwres_gnbarequest_parse()\fR
 131 and
 132 \fBlwres_gnbaresponse_parse()\fR
 133 all return
 134 \fBLWRES_R_SUCCESS\fR
 135 on success. They return
 136 \fBLWRES_R_NOMEMORY\fR
 137 if memory allocation fails.
 138 \fBLWRES_R_UNEXPECTEDEND\fR
 139 is returned if the available space in the buffer
 140 \fIb\fR
 141 is too small to accommodate the packet header or the
 142 \fBlwres_gnbarequest_t\fR
 143 and
 144 \fBlwres_gnbaresponse_t\fR
 145 structures.
 146 \fBlwres_gnbarequest_parse()\fR
 147 and
 148 \fBlwres_gnbaresponse_parse()\fR
 149 will return
 150 \fBLWRES_R_UNEXPECTEDEND\fR
 151 if the buffer is not empty after decoding the received packet. These functions will return
 152 \fBLWRES_R_FAILURE\fR
 153 if
 154 pktflags
 155 in the packet header structure
 156 \fBlwres_lwpacket_t\fR
 157 indicate that the packet is not a response to an earlier query.
 158 .SH "SEE ALSO"
 159 .PP
 160 \fBlwres_packet\fR(3).