lwres_getipnode.docbook revision c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85
6de8046f8f7e07cd83895a528df25d977e502c76nd<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd [<!ENTITY mdash "—">]>
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - Permission to use, copy, modify, and distribute this software for any
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd - purpose with or without fee is hereby granted, provided that the above
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd - copyright notice and this permission notice appear in all copies.
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
ce9621257ef9e54c1bbe5ad8a5f445a1f211c2dcnd - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - PERFORMANCE OF THIS SOFTWARE.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb<!-- $Id: lwres_getipnode.docbook,v 1.11 2007/01/29 23:57:22 marka Exp $ -->
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentryinfo>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </refentryinfo>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </refmeta>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <copyright>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </copyright>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <copyright>
7b4c4bb891261e613de39a021d7554fd08132fc5rbb </copyright>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </docinfo>
e6cc28a5eb3371ba0c38e941855e71ff0054f50erbb <refnamediv>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </refnamediv>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refsynopsisdiv>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <funcsynopsis>
97789c9dcc4cc724c9b80fb9b428d128c58e3e0and<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
97789c9dcc4cc724c9b80fb9b428d128c58e3e0and<funcprototype>
97789c9dcc4cc724c9b80fb9b428d128c58e3e0andstruct hostent *
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgstein <paramdef>const char *<parameter>name</parameter></paramdef>
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgstein <paramdef>int <parameter>flags</parameter></paramdef>
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgstein <paramdef>int *<parameter>error_num</parameter></paramdef>
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgstein </funcprototype>
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgstein<funcprototype>
e33a549ef7ad9ce23f4719d91de915e9ecedaecfgsteinstruct hostent *
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <paramdef>const void *<parameter>src</parameter></paramdef>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <paramdef>int *<parameter>error_num</parameter></paramdef>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </funcprototype>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb<funcprototype>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <paramdef>struct hostent *<parameter>he</parameter></paramdef>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </funcprototype>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb</funcsynopsis>
91a9b0a5d1aa9614c3d3361a66ebf570b5d0319cbrianp </refsynopsisdiv>
91a9b0a5d1aa9614c3d3361a66ebf570b5d0319cbrianp These functions perform thread safe, protocol independent
6dbbe8404a34c20c8594a21848a7c25c9728dbebnd nodename-to-address and address-to-nodename
6dbbe8404a34c20c8594a21848a7c25c9728dbebnd translation as defined in RFC2553.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb They use a
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb which is defined in
141b1a93f508248cbc0e9a124cc38041eb3e2562rbbstruct hostent {
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb char *h_name; /* official name of host */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb char **h_aliases; /* alias list */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb int h_addrtype; /* host address type */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb int h_length; /* length of address */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb char **h_addr_list; /* list of addresses from name server */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb#define h_addr h_addr_list[0] /* address, for backward compatibility */
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb</programlisting>
5d3e5520c34648220ed0cd9dc01c2c203257c86fnd The members of this structure are:
5d3e5520c34648220ed0cd9dc01c2c203257c86fnd <variablelist>
5d3e5520c34648220ed0cd9dc01c2c203257c86fnd <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb The official (canonical) name of the host.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb A NULL-terminated array of alternate names (nicknames) for the
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <listitem>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh The type of address being returned - usually
fee307b71a6c49d46a7ea2921b90df4243bf9db4wrowe </listitem>
b8daf4c5ea3d5bb2111b1b021de6d3cd891e403bcoar </varlistentry>
b8daf4c5ea3d5bb2111b1b021de6d3cd891e403bcoar <varlistentry>
b8daf4c5ea3d5bb2111b1b021de6d3cd891e403bcoar <listitem>
b8daf4c5ea3d5bb2111b1b021de6d3cd891e403bcoar The length of the address in bytes.
8496c88debb9962575dac2b1ef9b81984d7bd759brianp </listitem>
3d43d1454a609c00b8f35a19b416b86b85a029e6wrowe </varlistentry>
8419e6f8bff1a3617933f3ba760d2bdec7442f44coar <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <listitem>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz terminated array of network addresses for the host.
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz Host addresses are returned in network byte order.
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz </varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz </variablelist>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <para><function>lwres_getipnodebyname()</function>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz looks up addresses of protocol family <parameter>af</parameter>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz for the hostname <parameter>name</parameter>. The
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <parameter>flags</parameter> parameter contains ORed flag bits
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz to specify the types of addresses that are searched for, and the
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz types of addresses that are returned. The flag bits are:
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <variablelist>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz This is used with an
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz of AF_INET6, and causes IPv4 addresses to be returned as
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz IPv6 addresses.
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz </varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz This is used with an
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz be returned.
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh If AI_V4MAPPED is also set, the IPv4 addresses are return as
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz IPv6 addresses.
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz </varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <varlistentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh Only return an IPv6 or IPv4 address if here is an active network
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz interface of that type. This is not currently implemented
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz in the BIND 9 lightweight resolver, and the flag is ignored.
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz </varlistentry>
6db5333c9461942b8af724b101e687af541d4d4cjerenkrantz <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb This default sets the
f0a2d16b9c4129ec9deeb2131fdefe7e51dd1f38wrowe </listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </varlistentry>
f47b4ed53b56586ac250c2f70f511ef4e4e8332bwrowe </variablelist>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb performs a reverse lookup of address <parameter>src</parameter>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <parameter>af</parameter> denotes the protocol family, typically
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh releases all the memory associated with the <type>struct
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh hostent</type> pointer <parameter>he</parameter>. Any memory
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <constant>h_aliases</constant> is freed, as is the memory for
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh </refsect1>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refsect1>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh If an error occurs,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb to an appropriate error code and the function returns a
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb The error codes and their meanings are defined in
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <variablelist>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <varlistentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb No such host is known.
f0a2d16b9c4129ec9deeb2131fdefe7e51dd1f38wrowe </listitem>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb The server recognised the request and the name but no address is
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb available. Another type of request to the name server for the
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb domain might return an answer.
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh </listitem>
f0a2d16b9c4129ec9deeb2131fdefe7e51dd1f38wrowe </varlistentry>
d3dd4768a9cefb2391580911e4d01803f88052f1wrowe <varlistentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh A temporary and possibly transient error occurred, such as a
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh failure of a server to respond. The request may succeed if
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh </listitem>
6dbbe8404a34c20c8594a21848a7c25c9728dbebnd </varlistentry>
6dbbe8404a34c20c8594a21848a7c25c9728dbebnd <varlistentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <listitem>
f0a2d16b9c4129ec9deeb2131fdefe7e51dd1f38wrowe An unexpected failure occurred, and retrying the request
f0a2d16b9c4129ec9deeb2131fdefe7e51dd1f38wrowe is pointless.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </listitem>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh </varlistentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </variablelist>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh translates these error codes to suitable error messages.
fee307b71a6c49d46a7ea2921b90df4243bf9db4wrowe </refsect1>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <citerefentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <citerefentry>
2261031aa94be82d7e6b1b8c367afc1b282317f5ianh <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <citerefentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <citerefentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>,
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <citerefentry>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </citerefentry>.
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb </refsect1>
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - Local variables:
141b1a93f508248cbc0e9a124cc38041eb3e2562rbb - mode: sgml