lwres_resutil.html revision 8a66318e41ed14c5a88130e8c362610e8faa2121
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - Copyright (C) 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews<!-- $Id: lwres_resutil.html,v 1.9 2004/03/05 08:32:21 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_resutil</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
8a66318e41ed14c5a88130e8c362610e8faa2121Mark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBGCOLOR="#FFFFFF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonVLINK="#840084"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonALINK="#0000FF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_resutil</A
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFNAMEDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr -- lightweight resolver utility functions</DIV
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSYNOPSISDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSIS"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSISINFO"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_string_parse</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_addr_parse</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_buffer_t *b, lwres_addr_t *addr);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_getaddrsbyname</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_getnamebyaddr</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>DESCRIPTION</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_string_parse()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> retrieves a DNS-encoded
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonstring starting the current pointer of lightweight resolver buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>b->current</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the function returns, the address of the first byte of the
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonencoded string is returned via <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonlength of that string is given by <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonbuffer's current pointer is advanced to point at the character
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the string length, the encoded string, and the trailing
00380255bd1a9359fd3791ea33d5bee37af9e41aAndreas Gustafsson> character.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_addr_parse()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> extracts an address from the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
00380255bd1a9359fd3791ea33d5bee37af9e41aAndreas Gustafsson>. The buffer's current pointer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>b->current</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> is presumed to point at an encoded
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonaddress: the address preceded by a 32-bit protocol family identifier
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonand a 16-bit length field. The encoded address is copied to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>addr->address</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>addr->length</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> indicates the size in bytes of
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonthe address that was copied. <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>b->current</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonadvanced to point at the next byte of available data in the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the encoded address.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gnbaresponse_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure defined below:
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PROGRAMLISTING"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>typedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naddrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addrlist_t addrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t baselen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnresponse_t;</PRE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of this structure are not manipulated directly but
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthey are controlled through the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gabn</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The lightweight resolver uses
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> to perform foward lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> is looked up using the resolver
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> for memory allocation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> is a bitmask indicating which type of
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonaddresses are to be looked up. Current values for this bitmask are
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V4</SPAN
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> for IPv4 addresses and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V6</SPAN
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> for IPv6 addresses. Results of the
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonlookup are returned in <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> performs reverse lookups.
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas GustafssonResolver context <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> is used for memory
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonallocation. The address type is indicated by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V4</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V6</SPAN
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson>. The address to be looked up is given
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> and its length is
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> bytes. The result of the function call
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonis made available through <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>RETURN VALUES</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Successful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_string_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_addr_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS.</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBoth functions return
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_FAILURE</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer is corrupt or
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_UNEXPECTEDEND</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer has less space than expected for the components of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonencoded string or address.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonon success and it returns
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_NOTFOUND</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncould not be found.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned by a successful call to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_NOMEMORY</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhen memory allocation requests fail and
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_UNEXPECTEDEND</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffers used for sending queries and receiving replies are too
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_buffer</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gabn</SPAN