lwres_resutil.html revision 89da2a56413ba6294315bdde04f7547b9d71b062
5cd4555ad444fd391002ae32450572054369fd42Rob Austein - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Copyright (C) 2001 Internet Software Consortium.
4d42b714be10e6f163d23507e4e3a396a8ac0364Automatic Updater - Permission to use, copy, modify, and distribute this software for any
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - purpose with or without fee is hereby granted, provided that the above
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson - copyright notice and this permission notice appear in all copies.
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!-- $Id: lwres_resutil.html,v 1.13 2005/04/03 03:31:37 marka Exp $ -->
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_resutil</TITLE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinNAME="GENERATOR"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFENTRY"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinBGCOLOR="#FFFFFF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinTEXT="#000000"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinLINK="#0000FF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinVLINK="#840084"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinALINK="#0000FF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_resutil</H1
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFNAMEDIV"
4d42b714be10e6f163d23507e4e3a396a8ac0364Automatic Updater>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr -- lightweight resolver utility functions</DIV
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFSYNOPSISDIV"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>Synopsis</H2
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCSYNOPSIS"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCSYNOPSISINFO"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCDEF"
a268fec7f54a89a0772a91da0511c8eae09e6157Mark Andrews>lwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlwres_string_parse</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCDEF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlwres_addr_parse</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>(lwres_buffer_t *b, lwres_addr_t *addr);</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCDEF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlwres_getaddrsbyname</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCDEF"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlwres_getnamebyaddr</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFSECT1"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>DESCRIPTION</H2
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews>lwres_string_parse()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> retrieves a DNS-encoded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstring starting the current pointer of lightweight resolver buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CONSTANT"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>b->current</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinWhen the function returns, the address of the first byte of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinencoded string is returned via <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
d4f032db535ad5194d442fec535123f269422055Jeremy Reedlength of that string is given by <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbuffer's current pointer is advanced to point at the character
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfollowing the string length, the encoded string, and the trailing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> character.</P
065c66d9bf1c349600027bb50e3759a3736f73abMark AndrewsCLASS="FUNCTION"
d4f032db535ad5194d442fec535123f269422055Jeremy Reed>lwres_addr_parse()</CODE
d4f032db535ad5194d442fec535123f269422055Jeremy Reed> extracts an address from the
065c66d9bf1c349600027bb50e3759a3736f73abMark AndrewsCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>. The buffer's current pointer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CONSTANT"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>b->current</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> is presumed to point at an encoded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinaddress: the address preceded by a 32-bit protocol family identifier
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinand a 16-bit length field. The encoded address is copied to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CONSTANT"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>addr->address</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CONSTANT"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>addr->length</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> indicates the size in bytes of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinthe address that was copied. <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CONSTANT"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>b->current</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinadvanced to point at the next byte of available data in the buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfollowing the encoded address.</P
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getaddrsbyname()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getnamebyaddr()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_gnbaresponse_t</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstructure defined below:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PROGRAMLISTING"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>typedef struct {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint32_t flags;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t naliases;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t naddrs;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char *realname;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char **aliases;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t realnamelen;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t *aliaslen;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_addrlist_t addrs;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein size_t baselen;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein} lwres_gabnresponse_t;</PRE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe contents of this structure are not manipulated directly but
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinthey are controlled through the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CITEREFENTRY"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFENTRYTITLE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_gabn</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfunctions.</P
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>The lightweight resolver uses
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getaddrsbyname()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> to perform foward lookups.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinHostname <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> is looked up using the resolver
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincontext <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> for memory allocation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>addrtypes</CODE
0f78f780648806bcb3e374b7dafac73e6c558ea8Mark Andrews> is a bitmask indicating which type of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinaddresses are to be looked up. Current values for this bitmask are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_ADDRTYPE_V4</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> for IPv4 addresses and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_ADDRTYPE_V6</SPAN
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews> for IPv6 addresses. Results of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlookup are returned in <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>*structp</CODE
0db6bf459f7afa1f9dc0690a521df19955c89dbfJeremy ReedCLASS="FUNCTION"
0db6bf459f7afa1f9dc0690a521df19955c89dbfJeremy Reed>lwres_getnamebyaddr()</CODE
0db6bf459f7afa1f9dc0690a521df19955c89dbfJeremy Reed> performs reverse lookups.
0db6bf459f7afa1f9dc0690a521df19955c89dbfJeremy ReedResolver context <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> is used for memory
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinallocation. The address type is indicated by
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>addrtype</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_ADDRTYPE_V4</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_ADDRTYPE_V6</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>. The address to be looked up is given
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> and its length is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
8b9fc7617b8f54641708c985697848e6cc10a5bbMark Andrews>addrlen</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein> bytes. The result of the function call
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinis made available through <CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>*structp</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFSECT1"
1425217e5c3a2cbab7f8344e600e0c16047289ffMark Andrews>RETURN VALUES</H2
a268fec7f54a89a0772a91da0511c8eae09e6157Mark Andrews>Successful calls to
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark AndrewsCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_string_parse()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_addr_parse()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_SUCCESS.</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinBoth functions return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_FAILURE</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinif the buffer is corrupt or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_UNEXPECTEDEND</SPAN
c6d4f781529d2f28693546b25b2967d44ec89e60Mark Andrewsif the buffer has less space than expected for the components of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinencoded string or address.</P
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getaddrsbyname()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_SUCCESS</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinon success and it returns
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_NOTFOUND</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinif the hostname
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="PARAMETER"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeincould not be found.</P
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_SUCCESS</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinis returned by a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getnamebyaddr()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getaddrsbyname()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="FUNCTION"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_getnamebyaddr()</CODE
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>LWRES_R_NOMEMORY</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinwhen memory allocation requests fail and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="ERRORCODE"
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrews>LWRES_R_UNEXPECTEDEND</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinif the buffers used for sending queries and receiving replies are too
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFSECT1"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinNAME="AEN105"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>SEE ALSO</H2
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CITEREFENTRY"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFENTRYTITLE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_buffer</SPAN
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="CITEREFENTRY"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCLASS="REFENTRYTITLE"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein>lwres_gabn</SPAN