lwres_resutil.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - Copyright (C) 2000, 2001 Internet Software Consortium.
1708435e9c63465fd70c21025bd51cb44170d2dbdougm - Permission to use, copy, modify, and/or distribute this software for any
1708435e9c63465fd70c21025bd51cb44170d2dbdougm - purpose with or without fee is hereby granted, provided that the above
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - copyright notice and this permission notice appear in all copies.
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding - PERFORMANCE OF THIS SOFTWARE.
ff8c037448da2a14a00420b285ea3b8f2f4738e0fielding<!-- Converted by db4-upgrade version 1.0 -->
ff8c037448da2a14a00420b285ea3b8f2f4738e0fielding<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
75ad9d694b36c11047c0b747cf7fc31a4fdbf6e4dougm <refentryinfo>
75ad9d694b36c11047c0b747cf7fc31a4fdbf6e4dougm <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
75ad9d694b36c11047c0b747cf7fc31a4fdbf6e4dougm </refentryinfo>
f3220f54126b25e1cf93cc26c17177b7aef850fdfielding <copyright>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </copyright>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <copyright>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </copyright>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refnamediv>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refpurpose>lightweight resolver utility functions</refpurpose>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </refnamediv>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refsynopsisdiv>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <funcsynopsis>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley<funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolleylwres_result_t
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>char **<parameter>c</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley<funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolleylwres_result_t
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley<funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolleylwres_result_t
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>const char *<parameter>name</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley<funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolleylwres_result_t
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </funcprototype>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley</funcsynopsis>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </refsynopsisdiv>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refsection><info><title>DESCRIPTION</title></info>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley retrieves a DNS-encoded string starting the current pointer of
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lightweight resolver buffer <parameter>b</parameter>: i.e.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <constant>b->current</constant>. When the function returns,
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley the address of the first byte of the encoded string is returned
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley via <parameter>*c</parameter> and the length of that string is
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley given by <parameter>*len</parameter>. The buffer's current
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley pointer is advanced to point at the character following the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley string length, the encoded string, and the trailing
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley extracts an address from the buffer <parameter>b</parameter>.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley The buffer's current pointer <constant>b->current</constant>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley is presumed to point at an encoded address: the address preceded
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley by a 32-bit protocol family identifier and a 16-bit length
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley field. The encoded address is copied to
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <constant>addr->length</constant> indicates the size in bytes
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley of the address that was copied.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <constant>b->current</constant> is advanced to point at the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley next byte of available data in the buffer following the encoded
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley and <function>lwres_getnamebyaddr()</function> use the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <type>lwres_gnbaresponse_t</type> structure defined below:
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolleytypedef struct {
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lwres_uint32_t flags;
a8195ccda27932b4cd3ac09cda995dbcfdf5a195jwoolley lwres_uint16_t naliases;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lwres_uint16_t naddrs;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley char *realname;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley char **aliases;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lwres_uint16_t realnamelen;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lwres_uint16_t *aliaslen;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lwres_addrlist_t addrs;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley void *base;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley size_t baselen;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley} lwres_gabnresponse_t;
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley The contents of this structure are not manipulated directly but
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley they are controlled through the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <citerefentry>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </citerefentry>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley The lightweight resolver uses
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <function>lwres_getaddrsbyname()</function> to perform
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley forward lookups.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley Hostname <parameter>name</parameter> is looked up using the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley context <parameter>ctx</parameter> for memory allocation.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <parameter>addrtypes</parameter> is a bitmask indicating
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley which type of
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley addresses are to be looked up. Current values for this bitmask are
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley lookup are returned in <parameter>*structp</parameter>.
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley performs reverse lookups. Resolver context
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <parameter>ctx</parameter> is used for memory allocation. The
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley address type is indicated by <parameter>addrtype</parameter>:
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley given by <parameter>addr</parameter> and its length is
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <parameter>addrlen</parameter> bytes. The result of the
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley function call is made available through
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley </refsection>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley <refsection><info><title>RETURN VALUES</title></info>
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley Successful calls to
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley Both functions return
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley if the buffer is corrupt or
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley if the buffer has less space than expected for the components of the
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm encoded string or address.
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
a5a57eb904a8e19297b2c84596f24cede337f6edjwoolley is returned by a successful call to
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm when memory allocation requests fail and
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm if the buffers used for sending queries and receiving replies are too
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm </refsection>
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
e5d6e4b6e930968edfdc8e94c67988eb34382619dougm </citerefentry>,
960ca33b37540da5d863a4c0a88092d5ec85b3dadougm <citerefentry>
960ca33b37540da5d863a4c0a88092d5ec85b3dadougm <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
960ca33b37540da5d863a4c0a88092d5ec85b3dadougm </citerefentry>.
960ca33b37540da5d863a4c0a88092d5ec85b3dadougm </refsection>