.\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC").\" Copyright (C) 2000, 2001  Internet Software Consortium..\".\" Permission to use, copy, modify, and distribute this software for any.\" purpose with or without fee is hereby granted, provided that the above.\" copyright notice and this permission notice appear in all copies..\".\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY.\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR.\" PERFORMANCE OF THIS SOFTWARE..\".\" $Id: lwres_gabn.3,v 1.13.2.1.8.1 2004/03/06 07:41:42 marka Exp $.\".TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" "".SH NAMElwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling.SH SYNOPSIS\fB#include <lwres/lwres.h>.sp.nalwres_result_tlwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);.ad.sp.nalwres_result_tlwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);.ad.sp.nalwres_result_tlwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);.ad.sp.nalwres_result_tlwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);.ad.sp.navoidlwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);.ad.sp.navoidlwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);.ad\fR.SH "DESCRIPTION".PPThese are low-level routines for creating and parsinglightweight resolver name-to-address lookup request and response messages..PPThere are four main functions for the getaddrbyname opcode.One render function converts a getaddrbyname request structure \(em\fBlwres_gabnrequest_t\fR \(emto the lighweight resolver's canonical format.It is complemented by a parse function that converts a packet in thiscanonical format to a getaddrbyname request structure.Another render function converts the getaddrbyname response structure \(em\fBlwres_gabnresponse_t\fR \(emto the canonical format.This is complemented by a parse function which converts a packet incanonical format to a getaddrbyname response structure..PPThese structures are defined in\fI<lwres/lwres.h>\fR.They are shown below..sp.nf#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001Utypedef struct lwres_addr lwres_addr_t;typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;typedef struct {        lwres_uint32_t  flags;        lwres_uint32_t  addrtypes;        lwres_uint16_t  namelen;        char           *name;} lwres_gabnrequest_t;typedef struct {        lwres_uint32_t          flags;        lwres_uint16_t          naliases;        lwres_uint16_t          naddrs;        char                   *realname;        char                  **aliases;        lwres_uint16_t          realnamelen;        lwres_uint16_t         *aliaslen;        lwres_addrlist_t        addrs;        void                   *base;        size_t                  baselen;} lwres_gabnresponse_t;.sp.fi.PP\fBlwres_gabnrequest_render()\fRuses resolver context\fIctx\fRto convert getaddrbyname request structure\fIreq\fRto canonical format.The packet header structure\fIpkt\fRis initialised and transferred tobuffer\fIb\fR.The contents of\fI*req\fRare then appended to the buffer in canonical format.\fBlwres_gabnresponse_render()\fRperforms the same task, except it converts a getaddrbyname response structure\fBlwres_gabnresponse_t\fRto the lightweight resolver's canonical format..PP\fBlwres_gabnrequest_parse()\fRuses context\fIctx\fRto convert the contents of packet\fIpkt\fRto a\fBlwres_gabnrequest_t\fRstructure.Buffer\fIb\fRprovides space to be used for storing this structure.When the function succeeds, the resulting\fBlwres_gabnrequest_t\fRis made available through\fI*structp\fR.\fBlwres_gabnresponse_parse()\fRoffers the same semantics as\fBlwres_gabnrequest_parse()\fRexcept it yields a\fBlwres_gabnresponse_t\fRstructure..PP\fBlwres_gabnresponse_free()\fRand\fBlwres_gabnrequest_free()\fRrelease the memory in resolver context\fIctx\fRthat was allocated to the\fBlwres_gabnresponse_t\fRor\fBlwres_gabnrequest_t\fRstructures referenced via\fIstructp\fR.Any memory associated with ancillary buffers and strings for thosestructures is also discarded..SH "RETURN VALUES".PPThe getaddrbyname opcode functions\fBlwres_gabnrequest_render()\fR, \fBlwres_gabnresponse_render()\fR\fBlwres_gabnrequest_parse()\fRand\fBlwres_gabnresponse_parse()\fRall returnLWRES_R_SUCCESSon success.They returnLWRES_R_NOMEMORYif memory allocation fails.LWRES_R_UNEXPECTEDENDis returned if the available space in the buffer\fIb\fRis too small to accommodate the packet header or the\fBlwres_gabnrequest_t\fRand\fBlwres_gabnresponse_t\fRstructures.\fBlwres_gabnrequest_parse()\fRand\fBlwres_gabnresponse_parse()\fRwill returnLWRES_R_UNEXPECTEDENDif the buffer is not empty after decoding the received packet.These functions will returnLWRES_R_FAILUREif\fBpktflags\fRin the packet header structure\fBlwres_lwpacket_t\fRindicate that the packet is not a response to an earlier query..SH "SEE ALSO".PP\fBlwres_packet\fR(3)