lwres_getipnode.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
bb2a72a6e2327ae4f177c9d26e9d433033cfc27eaaron - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
2a6c49cfaef5979a5a06098f3ce987cd76769409manoj - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
2a6c49cfaef5979a5a06098f3ce987cd76769409manoj - Permission to use, copy, modify, and/or distribute this software for any
d8028365066fca602bf35d014530a1802114378crbb - purpose with or without fee is hereby granted, provided that the above
c25203fdca093d4504c51b4cd974ff60d5aa4fb1wrowe - copyright notice and this permission notice appear in all copies.
c25203fdca093d4504c51b4cd974ff60d5aa4fb1wrowe - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
d89c116f82699294ca744125723651c554bc5925wrowe - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
4214e98fc9045e5010e66f9a967bd6d68f40d342aaron - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8721697e2aece27b0e738519329f7976c72b27bfjerenkrantz - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
c25203fdca093d4504c51b4cd974ff60d5aa4fb1wrowe - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
91cacb801f6c0215b38322f6d2fc58cbfedfecfbjerenkrantz - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
91cacb801f6c0215b38322f6d2fc58cbfedfecfbjerenkrantz - PERFORMANCE OF THIS SOFTWARE.
df14f0d3a5191cdd7c4bb5b03acd135d43a6f51brbb<!-- Converted by db4-upgrade version 1.0 -->
ab71b233b3a36489e44a7b061c48293be0b17788jwoolley<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
bcb6e1be6041dfeb549c8ea8d37f97ad4e90a0c3rbb <refentryinfo>
2900ab946a2d76b73a14cebfe2985d253f01c967stoddard <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
a548c09e6a8ca1b059d0e93b5256c6ccb2b3c3cdrbb </refentryinfo>
2deb319e6b3de239f45c16a3e9e836d44f1f7108rbb <copyright>
af4c982a7cf4515f124935f99a329744035fc699slive <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
af4c982a7cf4515f124935f99a329744035fc699slive </copyright>
af4c982a7cf4515f124935f99a329744035fc699slive <copyright>
4b62424416882687387923b3130b96241503cbe0jerenkrantz </copyright>
5ca8e11fadb6f7a8d9d0367c1800205c99d4bcd6jerenkrantz <refnamediv>
8c8fbb8546af54582539898be704411a60058d85trawick <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
8c8fbb8546af54582539898be704411a60058d85trawick </refnamediv>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <refsynopsisdiv>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <funcsynopsis>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz<funcprototype>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantzstruct hostent *
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>const char *<parameter>name</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>int <parameter>af</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>int <parameter>flags</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>int *<parameter>error_num</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz </funcprototype>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz<funcprototype>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantzstruct hostent *
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz<function>lwres_getipnodebyaddr</function></funcdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>const void *<parameter>src</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>size_t <parameter>len</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz <paramdef>int <parameter>af</parameter></paramdef>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe <paramdef>int *<parameter>error_num</parameter></paramdef>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz </funcprototype>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz<funcprototype>
6f1e2a1eb9944358dc96ee52f2048377c57f1cfaaaron <paramdef>struct hostent *<parameter>he</parameter></paramdef>
6f1e2a1eb9944358dc96ee52f2048377c57f1cfaaaron </funcprototype>
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz</funcsynopsis>
1b3f48fd6b1ccb8745f908e40156c5a85ca3c347jerenkrantz </refsynopsisdiv>
bb2a72a6e2327ae4f177c9d26e9d433033cfc27eaaron These functions perform thread safe, protocol independent
bb2a72a6e2327ae4f177c9d26e9d433033cfc27eaaron nodename-to-address and address-to-nodename
bb2a72a6e2327ae4f177c9d26e9d433033cfc27eaaron translation as defined in RFC2553.
bb2a72a6e2327ae4f177c9d26e9d433033cfc27eaaron which is defined in
829b09b6ec9b6d69916813ef7205469bddc9f8a9gregamesstruct hostent {
829b09b6ec9b6d69916813ef7205469bddc9f8a9gregames char *h_name; /* official name of host */
829b09b6ec9b6d69916813ef7205469bddc9f8a9gregames char **h_aliases; /* alias list */
829b09b6ec9b6d69916813ef7205469bddc9f8a9gregames int h_addrtype; /* host address type */
8c8fbb8546af54582539898be704411a60058d85trawick int h_length; /* length of address */
8c8fbb8546af54582539898be704411a60058d85trawick char **h_addr_list; /* list of addresses from name server */
f9b8e29cfca92cf0a996e8ab17fa1a1f447cecc7stoddard#define h_addr h_addr_list[0] /* address, for backward compatibility */
f9b8e29cfca92cf0a996e8ab17fa1a1f447cecc7stoddard</programlisting>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe The members of this structure are:
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe <variablelist>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe <varlistentry>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe The official (canonical) name of the host.
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe </listitem>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe </varlistentry>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe <varlistentry>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe A NULL-terminated array of alternate names (nicknames) for the
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe </listitem>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe </varlistentry>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe <varlistentry>
638a9edaf48cf003cd40ac25ee8c25f572107414stoddard The type of address being returned - usually
db2d668e6233d8949b35ee7f9f42f444758f9ce9rbb </listitem>
db2d668e6233d8949b35ee7f9f42f444758f9ce9rbb </varlistentry>
db2d668e6233d8949b35ee7f9f42f444758f9ce9rbb <varlistentry>
db2d668e6233d8949b35ee7f9f42f444758f9ce9rbb <listitem>
1ea5221b240a8b41a07c6fb04aab5a73adcddabfaaron The length of the address in bytes.
1ea5221b240a8b41a07c6fb04aab5a73adcddabfaaron </listitem>
1ea5221b240a8b41a07c6fb04aab5a73adcddabfaaron </varlistentry>
a12f07383f9c286519fe88f559187148d5bd1c16aaron <varlistentry>
5d12baef135b5d3cb94745e007a1575398469724jerenkrantz terminated array of network addresses for the host.
5d12baef135b5d3cb94745e007a1575398469724jerenkrantz Host addresses are returned in network byte order.
5d12baef135b5d3cb94745e007a1575398469724jerenkrantz </varlistentry>
5d12baef135b5d3cb94745e007a1575398469724jerenkrantz </variablelist>
5d12baef135b5d3cb94745e007a1575398469724jerenkrantz <para><function>lwres_getipnodebyname()</function>
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz looks up addresses of protocol family <parameter>af</parameter>
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz for the hostname <parameter>name</parameter>. The
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz <parameter>flags</parameter> parameter contains ORed flag bits
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz to specify the types of addresses that are searched for, and the
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz types of addresses that are returned. The flag bits are:
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz <variablelist>
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz <varlistentry>
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz This is used with an
b865daaa4ef731a7066ee6d97e2aae36c7743939jerenkrantz of AF_INET6, and causes IPv4 addresses to be returned as
dc098c7ce5d36179c504d09fc722d190683d0262aaron IPv6 addresses.
dc098c7ce5d36179c504d09fc722d190683d0262aaron </listitem>
dc098c7ce5d36179c504d09fc722d190683d0262aaron </varlistentry>
dc098c7ce5d36179c504d09fc722d190683d0262aaron <varlistentry>
364dfd4527e6ce37b828a42e2c0bbdf9ba19a9b8gregames This is used with an
0bcb1fe39dfaacf9745b6633f5cc9ebc8e2596caaaron of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
0bcb1fe39dfaacf9745b6633f5cc9ebc8e2596caaaron be returned.
0bcb1fe39dfaacf9745b6633f5cc9ebc8e2596caaaron If AI_V4MAPPED is also set, the IPv4 addresses are return as
0bcb1fe39dfaacf9745b6633f5cc9ebc8e2596caaaron IPv6 addresses.
33f5961d34a8b5390cebad0543b3ebe67830e5d7jerenkrantz </varlistentry>
33f5961d34a8b5390cebad0543b3ebe67830e5d7jerenkrantz <varlistentry>
ff42f83cbf31893bcde9712332a8e5ee970f6a74trawick Only return an IPv6 or IPv4 address if here is an active network
ff42f83cbf31893bcde9712332a8e5ee970f6a74trawick interface of that type. This is not currently implemented
ff42f83cbf31893bcde9712332a8e5ee970f6a74trawick in the BIND 9 lightweight resolver, and the flag is ignored.
54e1babd5a5a56c576eeeace54110150769cc916coar </listitem>
54e1babd5a5a56c576eeeace54110150769cc916coar </varlistentry>
54e1babd5a5a56c576eeeace54110150769cc916coar <varlistentry>
54e1babd5a5a56c576eeeace54110150769cc916coar <listitem>
54e1babd5a5a56c576eeeace54110150769cc916coar This default sets the
54e1babd5a5a56c576eeeace54110150769cc916coar flag bits.
54e1babd5a5a56c576eeeace54110150769cc916coar </listitem>
949aa7bba7f804faa8e6b08cad42a98fc0255d85jerenkrantz </varlistentry>
949aa7bba7f804faa8e6b08cad42a98fc0255d85jerenkrantz </variablelist>
949aa7bba7f804faa8e6b08cad42a98fc0255d85jerenkrantz <para><function>lwres_getipnodebyaddr()</function>
949aa7bba7f804faa8e6b08cad42a98fc0255d85jerenkrantz performs a reverse lookup of address <parameter>src</parameter>
e0427bf8e52a8fb920cb8b6adb5cdb3b6535b7fecoar <parameter>af</parameter> denotes the protocol family, typically
07021d9f405849228b859d9fb4b877f20e4fbba3jerenkrantz releases all the memory associated with the <type>struct
f126ee03179eb54308118f1ec3de5a7b461685d8aaron hostent</type> pointer <parameter>he</parameter>. Any memory
f126ee03179eb54308118f1ec3de5a7b461685d8aaron <constant>h_aliases</constant> is freed, as is the memory for
f126ee03179eb54308118f1ec3de5a7b461685d8aaron </refsection>
f126ee03179eb54308118f1ec3de5a7b461685d8aaron If an error occurs,
109faf633e12ab0bbdd602c7addc795cce59e8addreid to an appropriate error code and the function returns a
109faf633e12ab0bbdd602c7addc795cce59e8addreid The error codes and their meanings are defined in
109faf633e12ab0bbdd602c7addc795cce59e8addreid <variablelist>
109faf633e12ab0bbdd602c7addc795cce59e8addreid <varlistentry>
109faf633e12ab0bbdd602c7addc795cce59e8addreid No such host is known.
109faf633e12ab0bbdd602c7addc795cce59e8addreid </listitem>
4ca13a5e126946272f02637e268a8e09193c553ecoar </varlistentry>
4ca13a5e126946272f02637e268a8e09193c553ecoar <varlistentry>
4ca13a5e126946272f02637e268a8e09193c553ecoar <listitem>
48c0c81cd6fabac9d3386406d97633780365b839coar The server recognised the request and the name but no address is
48c0c81cd6fabac9d3386406d97633780365b839coar available. Another type of request to the name server for the
48c0c81cd6fabac9d3386406d97633780365b839coar domain might return an answer.
48c0c81cd6fabac9d3386406d97633780365b839coar </listitem>
48c0c81cd6fabac9d3386406d97633780365b839coar </varlistentry>
48c0c81cd6fabac9d3386406d97633780365b839coar <varlistentry>
4ca13a5e126946272f02637e268a8e09193c553ecoar <listitem>
b84f66c93f820824b1d5455181f55598b766319cwrowe A temporary and possibly transient error occurred, such as a
b84f66c93f820824b1d5455181f55598b766319cwrowe failure of a server to respond. The request may succeed if
7fe18c15b669db9d191859695901dc4fcf3829dawrowe </listitem>
7fe18c15b669db9d191859695901dc4fcf3829dawrowe </varlistentry>
7fe18c15b669db9d191859695901dc4fcf3829dawrowe <varlistentry>
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe An unexpected failure occurred, and retrying the request
d24a92b8a8315e9a266ba84cc2a996d49dd546c1stoddard is pointless.
48c0c81cd6fabac9d3386406d97633780365b839coar </listitem>
48c0c81cd6fabac9d3386406d97633780365b839coar </varlistentry>
2fb49a1d25f38421a68d31b4cbb5d9293fdeafbewrowe </variablelist>
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe </citerefentry>
60d567a0c2aae815ee6fc20c0d65032bea52c92cwrowe translates these error codes to suitable error messages.
7239216999e746bb4fc7671621becea33c5c1c87stoddard </refsection>
3913a3b7e7c72ea11d05da36275db39c2dc39b68jwoolley </citerefentry>,
57710387e669ee41fb211458efe09c4c73194a66jwoolley <citerefentry>
3913a3b7e7c72ea11d05da36275db39c2dc39b68jwoolley <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
3913a3b7e7c72ea11d05da36275db39c2dc39b68jwoolley </citerefentry>,
19cbe4d7b7c931723e7249de6829bf965a1fee72stoddard <citerefentry>
19cbe4d7b7c931723e7249de6829bf965a1fee72stoddard <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
b187d568e1507d75139ebc13ca945b38fc05d55cstoddard </citerefentry>,
b187d568e1507d75139ebc13ca945b38fc05d55cstoddard <citerefentry>
1c6fb1e726ce22694de0e9a957adb67b929e5d4fstoddard <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
1c6fb1e726ce22694de0e9a957adb67b929e5d4fstoddard </citerefentry>,
d2f8b010487ffa990a9c268df5a25579e7291bcdrbb <citerefentry>
d2f8b010487ffa990a9c268df5a25579e7291bcdrbb <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
a5ed555df952c85bc1b179f5981e8a6c54ba16e6stoddard </citerefentry>,
0bff2f28ef945280c17099c142126178a78e1e54manoj <citerefentry>
0bff2f28ef945280c17099c142126178a78e1e54manoj <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
1e585ba09ea32272e63c4c39c35491e975d21d98stoddard </citerefentry>.
35330e0d79ceb8027223bbb8330a381b1f989d6etrawick </refsection>