lwres_resutil.html revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson - Copyright (C) 2000, 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_resutil</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCONTENT="Modular DocBook HTML Stylesheet Version 1.61
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
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonretrieves a DNS-encoded string starting the current pointer of
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlightweight 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
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonencoded string is returned via
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand the length of that string is given by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe buffer's current pointer is advanced to point at the character
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the string length, the encoded string, and the trailing
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_string_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonhas an assertion check that
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_addr_parse()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonextracts an address from the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe buffer's current pointer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>b->current</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis presumed to point at an encoded address: the address preceded by a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson32-bit protocol family identifier and a 16-bit length field.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe encoded address is copied to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>addr->address</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>addr->length</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindicates the size in bytes of the address that was copied.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>b->current</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis advanced 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
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto perform foward lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis looked up using the resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor memory allocation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a bitmask indicating which type of addresses are to be looked up.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCurrent values for this bitmask are
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V4</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor IPv4 addresses and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V6</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor IPv6 addresses.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResults of the lookup are returned in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonchecks that its pointer arguments are not
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis non-zero.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms reverse lookups.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis used for memory allocation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe address type is indicated by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V4</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_ADDRTYPE_V6</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe address to be looked up is given by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand its length is
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe result of the function call is made available through
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnamebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonuses assertion checking to ensure its pointer arguments are not
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrsbyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonalso checks that
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis non-zero.</P
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