lwres_getipnode.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Copyright (C) 2000, 2001 Internet Software Consortium.
1b06367c345e972a0c719a6e821db3e875f20c3bMark Andrews - Permission to use, copy, modify, and distribute this software for any
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - purpose with or without fee is hereby granted, provided that the above
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - copyright notice and this permission notice appear in all copies.
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews<!-- $Id: lwres_getipnode.docbook,v 1.1 2001/03/31 00:08:12 gson Exp $ -->
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<refentryinfo>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews</refentryinfo>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews</refnamediv>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<refsynopsisdiv>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<funcprototype>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsstruct hostent *
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<function>lwres_getipnodebyname</function></funcdef>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews</funcprototype>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrews<funcprototype>
33d96fbbc8aa221508f3c780539bf44810fd2c9cMark Andrewsstruct hostent *
819fe493f97078521bb6b9a7b97583bef89f5abcMark Andrews<function>lwres_getipnodebyaddr</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThese functions perform thread safe, protocol independent
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinnodename-to-address and address-to-nodename
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintranslation as defined in RFC2553.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinwhich is defined in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstruct hostent {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char *h_name; /* official name of host */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char **h_aliases; /* alias list */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int h_addrtype; /* host address type */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int h_length; /* length of address */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char **h_addr_list; /* list of addresses from name server */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#define h_addr h_addr_list[0] /* address, for backward compatibility */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe members of this structure are:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>h_name</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe official (canonical) name of the host.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>h_aliases</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinA NULL-terminated array of alternate names (nicknames) for the host.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>h_addrtype</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe type of address being returned - usually
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>h_length</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe length of the address in bytes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>h_addr_list</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinterminated array of network addresses for the host.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinHost addresses are returned in network byte order.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlooks up addresses of protocol family
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfor the hostname
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinparameter contains ORed flag bits to
8d709e3ee443222cd35e44eadc9a4c0a8d92fec2Rob Austeinspecify the types of addresses that are searched
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfor, and the types of addresses that are returned.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe flag bits are:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>AI_V4MAPPED</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThis is used with an
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIPv6 addresses.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>AI_ALL</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThis is used with an
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIPv6 addresses.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinOnly return an IPv6 or IPv4 address if here is an active network
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeininterface of that type. This is not currently implemented
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinin the BIND 9 lightweight resolver, and the flag is ignored.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>AI_DEFAULT</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThis default sets the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinperforms a reverse lookup
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindenotes the protocol family, typically
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinreleases all the memory associated with
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAny memory allocated for the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinis freed, as is the memory for the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinstructure itself.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIf an error occurs,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinto an approriate error code and the function returns a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe error codes and their meanings are defined in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinNo such host is known.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>NO_ADDRESS</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe server recognised the request and the name but no address is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinavailable. Another type of request to the name server for the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindomain might return an answer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>TRY_AGAIN</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinA temporary and possibly transient error occurred, such as a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinfailure of a server to respond. The request may succeed if
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<varlistentry><term><constant>NO_RECOVERY</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAn unexpected failure occurred, and retrying the request
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinis pointless.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintranslates these error codes to suitable error messages.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</citerefentry>.