diff options
Diffstat (limited to 'contrib/bind9/lib/lwres/man/lwres_resutil.html')
| -rw-r--r-- | contrib/bind9/lib/lwres/man/lwres_resutil.html | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/contrib/bind9/lib/lwres/man/lwres_resutil.html b/contrib/bind9/lib/lwres/man/lwres_resutil.html new file mode 100644 index 0000000..cc45556 --- /dev/null +++ b/contrib/bind9/lib/lwres/man/lwres_resutil.html @@ -0,0 +1,387 @@ +<!-- + - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 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_resutil.html,v 1.8.2.1.4.2 2004/08/22 23:39:05 marka Exp $ --> + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML +><HEAD +><TITLE +>lwres_resutil</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><H1 +><A +NAME="AEN1" +></A +>lwres_resutil</H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN8" +></A +><H2 +>Name</H2 +>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr -- lightweight resolver utility functions</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN14" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN15" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <lwres/lwres.h></PRE +><P +><CODE +><CODE +CLASS="FUNCDEF" +>lwres_result_t +lwres_string_parse</CODE +>(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE +></P +><P +><CODE +><CODE +CLASS="FUNCDEF" +>lwres_result_t +lwres_addr_parse</CODE +>(lwres_buffer_t *b, lwres_addr_t *addr);</CODE +></P +><P +><CODE +><CODE +CLASS="FUNCDEF" +>lwres_result_t +lwres_getaddrsbyname</CODE +>(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE +></P +><P +><CODE +><CODE +CLASS="FUNCDEF" +>lwres_result_t +lwres_getnamebyaddr</CODE +>(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE +></P +><P +></P +></DIV +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN43" +></A +><H2 +>DESCRIPTION</H2 +><P +><CODE +CLASS="FUNCTION" +>lwres_string_parse()</CODE +> retrieves a DNS-encoded +string starting the current pointer of lightweight resolver buffer +<VAR +CLASS="PARAMETER" +>b</VAR +>: i.e. <CODE +CLASS="CONSTANT" +>b->current</CODE +>. +When the function returns, the address of the first byte of the +encoded string is returned via <VAR +CLASS="PARAMETER" +>*c</VAR +> and the +length of that string is given by <VAR +CLASS="PARAMETER" +>*len</VAR +>. The +buffer's current pointer is advanced to point at the character +following the string length, the encoded string, and the trailing +<SPAN +CLASS="TYPE" +>NULL</SPAN +> character.</P +><P +><CODE +CLASS="FUNCTION" +>lwres_addr_parse()</CODE +> extracts an address from the +buffer <VAR +CLASS="PARAMETER" +>b</VAR +>. The buffer's current pointer +<CODE +CLASS="CONSTANT" +>b->current</CODE +> is presumed to point at an encoded +address: the address preceded by a 32-bit protocol family identifier +and a 16-bit length field. The encoded address is copied to +<CODE +CLASS="CONSTANT" +>addr->address</CODE +> and +<CODE +CLASS="CONSTANT" +>addr->length</CODE +> indicates the size in bytes of +the address that was copied. <CODE +CLASS="CONSTANT" +>b->current</CODE +> is +advanced to point at the next byte of available data in the buffer +following the encoded address.</P +><P +><CODE +CLASS="FUNCTION" +>lwres_getaddrsbyname()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_getnamebyaddr()</CODE +> +use the +<SPAN +CLASS="TYPE" +>lwres_gnbaresponse_t</SPAN +> +structure defined below: +<PRE +CLASS="PROGRAMLISTING" +>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;</PRE +> +The contents of this structure are not manipulated directly but +they are controlled through the +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_gabn</SPAN +>(3)</SPAN +> +functions.</P +><P +>The lightweight resolver uses +<CODE +CLASS="FUNCTION" +>lwres_getaddrsbyname()</CODE +> to perform foward lookups. +Hostname <VAR +CLASS="PARAMETER" +>name</VAR +> is looked up using the resolver +context <VAR +CLASS="PARAMETER" +>ctx</VAR +> for memory allocation. +<VAR +CLASS="PARAMETER" +>addrtypes</VAR +> is a bitmask indicating which type of +addresses are to be looked up. Current values for this bitmask are +<SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V4</SPAN +> for IPv4 addresses and +<SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V6</SPAN +> for IPv6 addresses. Results of the +lookup are returned in <VAR +CLASS="PARAMETER" +>*structp</VAR +>.</P +><P +><CODE +CLASS="FUNCTION" +>lwres_getnamebyaddr()</CODE +> performs reverse lookups. +Resolver context <VAR +CLASS="PARAMETER" +>ctx</VAR +> is used for memory +allocation. The address type is indicated by +<VAR +CLASS="PARAMETER" +>addrtype</VAR +>: <SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V4</SPAN +> or +<SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V6</SPAN +>. The address to be looked up is given +by <VAR +CLASS="PARAMETER" +>addr</VAR +> and its length is +<VAR +CLASS="PARAMETER" +>addrlen</VAR +> bytes. The result of the function call +is made available through <VAR +CLASS="PARAMETER" +>*structp</VAR +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN84" +></A +><H2 +>RETURN VALUES</H2 +><P +>Successful calls to +<CODE +CLASS="FUNCTION" +>lwres_string_parse()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_addr_parse()</CODE +> +return +<SPAN +CLASS="ERRORCODE" +>LWRES_R_SUCCESS.</SPAN +> +Both functions return +<SPAN +CLASS="ERRORCODE" +>LWRES_R_FAILURE</SPAN +> +if the buffer is corrupt or +<SPAN +CLASS="ERRORCODE" +>LWRES_R_UNEXPECTEDEND</SPAN +> +if the buffer has less space than expected for the components of the +encoded string or address.</P +><P +><CODE +CLASS="FUNCTION" +>lwres_getaddrsbyname()</CODE +> +returns +<SPAN +CLASS="ERRORCODE" +>LWRES_R_SUCCESS</SPAN +> +on success and it returns +<SPAN +CLASS="ERRORCODE" +>LWRES_R_NOTFOUND</SPAN +> +if the hostname +<VAR +CLASS="PARAMETER" +>name</VAR +> +could not be found.</P +><P +><SPAN +CLASS="ERRORCODE" +>LWRES_R_SUCCESS</SPAN +> +is returned by a successful call to +<CODE +CLASS="FUNCTION" +>lwres_getnamebyaddr()</CODE +>.</P +><P +>Both +<CODE +CLASS="FUNCTION" +>lwres_getaddrsbyname()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_getnamebyaddr()</CODE +> +return +<SPAN +CLASS="ERRORCODE" +>LWRES_R_NOMEMORY</SPAN +> +when memory allocation requests fail and +<SPAN +CLASS="ERRORCODE" +>LWRES_R_UNEXPECTEDEND</SPAN +> +if the buffers used for sending queries and receiving replies are too +small.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN105" +></A +><H2 +>SEE ALSO</H2 +><P +><SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_buffer</SPAN +>(3)</SPAN +>, + +<SPAN +CLASS="CITEREFENTRY" +><SPAN +CLASS="REFENTRYTITLE" +>lwres_gabn</SPAN +>(3)</SPAN +>.</P +></DIV +></BODY +></HTML +> |
