diff options
Diffstat (limited to 'lib/liblwres/man/lwres_resutil.html')
| -rw-r--r-- | lib/liblwres/man/lwres_resutil.html | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/lib/liblwres/man/lwres_resutil.html b/lib/liblwres/man/lwres_resutil.html new file mode 100644 index 000000000..ae3a2f646 --- /dev/null +++ b/lib/liblwres/man/lwres_resutil.html @@ -0,0 +1,412 @@ +<!-- + - 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 INTERNET SOFTWARE CONSORTIUM + - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL + - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL + - INTERNET SOFTWARE CONSORTIUM 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. +--> +<HTML +><HEAD +><TITLE +>lwres_resutil</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"></HEAD +><BODY +CLASS="REFENTRY" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><H1 +><A +NAME="AEN1" +>lwres_resutil</A +></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" +><A +NAME="AEN15" +></A +><P +></P +><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 +><TT +CLASS="FUNCTION" +>lwres_string_parse()</TT +> retrieves a DNS-encoded +string starting the current pointer of lightweight resolver buffer +<TT +CLASS="PARAMETER" +><I +>b</I +></TT +>: i.e. <TT +CLASS="CONSTANT" +>b->current</TT +>. +When the function returns, the address of the first byte of the +encoded string is returned via <TT +CLASS="PARAMETER" +><I +>*c</I +></TT +> and the +length of that string is given by <TT +CLASS="PARAMETER" +><I +>*len</I +></TT +>. 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 +><TT +CLASS="FUNCTION" +>lwres_addr_parse()</TT +> extracts an address from the +buffer <TT +CLASS="PARAMETER" +><I +>b</I +></TT +>. The buffer's current pointer +<TT +CLASS="CONSTANT" +>b->current</TT +> 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 +<TT +CLASS="CONSTANT" +>addr->address</TT +> and +<TT +CLASS="CONSTANT" +>addr->length</TT +> indicates the size in bytes of +the address that was copied. <TT +CLASS="CONSTANT" +>b->current</TT +> is +advanced to point at the next byte of available data in the buffer +following the encoded address.</P +><P +><TT +CLASS="FUNCTION" +>lwres_getaddrsbyname()</TT +> +and +<TT +CLASS="FUNCTION" +>lwres_getnamebyaddr()</TT +> +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 +<TT +CLASS="FUNCTION" +>lwres_getaddrsbyname()</TT +> to perform foward lookups. +Hostname <TT +CLASS="PARAMETER" +><I +>name</I +></TT +> is looked up using the resolver +context <TT +CLASS="PARAMETER" +><I +>ctx</I +></TT +> for memory allocation. +<TT +CLASS="PARAMETER" +><I +>addrtypes</I +></TT +> 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 <TT +CLASS="PARAMETER" +><I +>*structp</I +></TT +>.</P +><P +><TT +CLASS="FUNCTION" +>lwres_getnamebyaddr()</TT +> performs reverse lookups. +Resolver context <TT +CLASS="PARAMETER" +><I +>ctx</I +></TT +> is used for memory +allocation. The address type is indicated by +<TT +CLASS="PARAMETER" +><I +>addrtype</I +></TT +>: <SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V4</SPAN +> or +<SPAN +CLASS="TYPE" +>LWRES_ADDRTYPE_V6</SPAN +>. The address to be looked up is given +by <TT +CLASS="PARAMETER" +><I +>addr</I +></TT +> and its length is +<TT +CLASS="PARAMETER" +><I +>addrlen</I +></TT +> bytes. The result of the function call +is made available through <TT +CLASS="PARAMETER" +><I +>*structp</I +></TT +>.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN84" +></A +><H2 +>RETURN VALUES</H2 +><P +>Successful calls to +<TT +CLASS="FUNCTION" +>lwres_string_parse()</TT +> +and +<TT +CLASS="FUNCTION" +>lwres_addr_parse()</TT +> +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 +><TT +CLASS="FUNCTION" +>lwres_getaddrsbyname()</TT +> +returns +<SPAN +CLASS="ERRORCODE" +>LWRES_R_SUCCESS</SPAN +> +on success and it returns +<SPAN +CLASS="ERRORCODE" +>LWRES_R_NOTFOUND</SPAN +> +if the hostname +<TT +CLASS="PARAMETER" +><I +>name</I +></TT +> +could not be found.</P +><P +><SPAN +CLASS="ERRORCODE" +>LWRES_R_SUCCESS</SPAN +> +is returned by a successful call to +<TT +CLASS="FUNCTION" +>lwres_getnamebyaddr()</TT +>.</P +><P +>Both +<TT +CLASS="FUNCTION" +>lwres_getaddrsbyname()</TT +> +and +<TT +CLASS="FUNCTION" +>lwres_getnamebyaddr()</TT +> +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 +>
\ No newline at end of file |