lwres_getipnode.docbook revision 14a656f94b1fd0ababd84a772228dfa52276ba15
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
16f816d3f3c32ae3351834253f52ddd0212bcbf3Timo Sirainen - Permission to use, copy, modify, and/or distribute this software for any
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - purpose with or without fee is hereby granted, provided that the above
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - copyright notice and this permission notice appear in all copies.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
463e82bdf0e990f4f2252d2b53ea23a5abe5883cTimo Sirainen - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a0d34d3982507f513a9d800082481e9faeb9a943Timo Sirainen - PERFORMANCE OF THIS SOFTWARE.
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen<!-- Converted by db4-upgrade version 1.0 -->
e6d7d19c328e7043ad35d5a52c1617bde915a16fTimo Sirainen<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
d7095f3a4466fbb78b2d5eb3d322bc15a5b0ab1fTimo Sirainen <refentryinfo>
8f7b00599e73fe71b1d2c6c65f8ae98aac1b23fbTimo Sirainen <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
8f7b00599e73fe71b1d2c6c65f8ae98aac1b23fbTimo Sirainen </refentryinfo>
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen <refentrytitle>lwres_getipnode</refentrytitle>
9315dd69233d554452df0c12bc57002d2042a8f4Timo Sirainen <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
538c58fc95200fcc5e91abdda8b912b574a2f968Timo Sirainen <holder>Internet Software Consortium.</holder>
d482b35af87f5fd872bad007da0475813a401a49Timo Sirainen <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
d482b35af87f5fd872bad007da0475813a401a49Timo Sirainen </refnamediv>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <refsynopsisdiv>
d482b35af87f5fd872bad007da0475813a401a49Timo Sirainen <funcsynopsis>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainenstruct hostent *
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<function>lwres_getipnodebyname</function></funcdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <paramdef>const char *<parameter>name</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <paramdef>int <parameter>af</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <paramdef>int <parameter>flags</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <paramdef>int *<parameter>error_num</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen </funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainenstruct hostent *
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<function>lwres_getipnodebyaddr</function></funcdef>
d482b35af87f5fd872bad007da0475813a401a49Timo Sirainen <paramdef>const void *<parameter>src</parameter></paramdef>
d482b35af87f5fd872bad007da0475813a401a49Timo Sirainen <paramdef>size_t <parameter>len</parameter></paramdef>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <paramdef>int <parameter>af</parameter></paramdef>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <paramdef>int *<parameter>error_num</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen </funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen<function>lwres_freehostent</function></funcdef>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <paramdef>struct hostent *<parameter>he</parameter></paramdef>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen </funcprototype>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen</funcsynopsis>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen </refsynopsisdiv>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen <refsection><info><title>DESCRIPTION</title></info>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen These functions perform thread safe, protocol independent
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen nodename-to-address and address-to-nodename
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen translation as defined in RFC2553.
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen which is defined in
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainenstruct hostent {
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen char *h_name; /* official name of host */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen char **h_aliases; /* alias list */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen int h_addrtype; /* host address type */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen int h_length; /* length of address */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen char **h_addr_list; /* list of addresses from name server */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen#define h_addr h_addr_list[0] /* address, for backward compatibility */
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen</programlisting>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen The members of this structure are:
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen <variablelist>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen <varlistentry>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen The official (canonical) name of the host.
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen </varlistentry>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen <varlistentry>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen A NULL-terminated array of alternate names (nicknames) for the
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen </varlistentry>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen <varlistentry>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen The type of address being returned - usually
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen </varlistentry>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <varlistentry>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen The length of the address in bytes.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen </varlistentry>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <varlistentry>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen terminated array of network addresses for the host.
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen Host addresses are returned in network byte order.
287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen </varlistentry>
287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen </variablelist>
9887c39c5ba429169389153ca99de49e084a73f0Timo Sirainen <para><function>lwres_getipnodebyname()</function>
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen looks up addresses of protocol family <parameter>af</parameter>
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen for the hostname <parameter>name</parameter>. The
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen <parameter>flags</parameter> parameter contains ORed flag bits
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen to specify the types of addresses that are searched for, and the
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen types of addresses that are returned. The flag bits are:
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen <variablelist>
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen <varlistentry>
d7095f3a4466fbb78b2d5eb3d322bc15a5b0ab1fTimo Sirainen This is used with an
bbf796c17f02538058d7559bfe96d677e5b55015Timo Sirainen of AF_INET6, and causes IPv4 addresses to be returned as
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen IPv6 addresses.
41bb0aa8e357876bc9a1916a37c9e3e78e5f8185Timo Sirainen </varlistentry>
567e57b09a49bbb2a146b13f8617698eb56237feTimo Sirainen <varlistentry>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen This is used with an
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
9315dd69233d554452df0c12bc57002d2042a8f4Timo Sirainen If AI_V4MAPPED is also set, the IPv4 addresses are return as
7889c9f65e23c83fc31cecf304cab4ab070d6aa1Timo Sirainen IPv6 addresses.
287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen </varlistentry>
287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen <varlistentry>
287ba82a8da3eaa473b5735d4eeac2fb4c5d8117Timo Sirainen <term><constant>AI_ADDRCONFIG</constant></term>
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen Only return an IPv6 or IPv4 address if here is an active network
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen interface of that type. This is not currently implemented
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen in the BIND 9 lightweight resolver, and the flag is ignored.
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen </varlistentry>
fa5957ffc9b676bfd649fa9953e63e72ee4ebeb4Timo Sirainen <varlistentry>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen This default sets the
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen </varlistentry>
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen </variablelist>
6a19e109ee8c5a6f688da83a86a7f6abeb71abddTimo Sirainen <para><function>lwres_getipnodebyaddr()</function>
da985034a708db2f61394b30d117050ae6829ee5Timo Sirainen performs a reverse lookup of address <parameter>src</parameter>
da985034a708db2f61394b30d117050ae6829ee5Timo Sirainen which is <parameter>len</parameter> bytes long.
da985034a708db2f61394b30d117050ae6829ee5Timo Sirainen <parameter>af</parameter> denotes the protocol family, typically
da985034a708db2f61394b30d117050ae6829ee5Timo Sirainen <type>PF_INET</type> or <type>PF_INET6</type>.
8e7da21696c9f8a6d5e601243fb6172ec85d47b2Timo Sirainen <para><function>lwres_freehostent()</function>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen releases all the memory associated with the <type>struct
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen hostent</type> pointer <parameter>he</parameter>. Any memory
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen allocated for the <constant>h_name</constant>,
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen <constant>h_aliases</constant> is freed, as is the memory for
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen </refsection>
3cdea46b2af97ab30861ee235678822278217514Timo Sirainen <refsection><info><title>RETURN VALUES</title></info>
8e7da21696c9f8a6d5e601243fb6172ec85d47b2Timo Sirainen If an error occurs,
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen to an appropriate error code and the function returns a
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen The error codes and their meanings are defined in
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <variablelist>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <varlistentry>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <term><constant>HOST_NOT_FOUND</constant></term>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen No such host is known.
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen </varlistentry>
7394389230750c45b105cdefb5850c81cae8cdc0Timo Sirainen <varlistentry>
7e94cf9d70ce9fdeccb7a85ff400b899e6386f36Timo Sirainen The server recognised the request and the name but no address is
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen available. Another type of request to the name server for the
9887c39c5ba429169389153ca99de49e084a73f0Timo Sirainen domain might return an answer.
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen </varlistentry>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen <varlistentry>
ace3c14e47a5a865df8aeea2fabc993b609dd163Timo Sirainen A temporary and possibly transient error occurred, such as a
7e94cf9d70ce9fdeccb7a85ff400b899e6386f36Timo Sirainen failure of a server to respond. The request may succeed if
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen </varlistentry>
ace3c14e47a5a865df8aeea2fabc993b609dd163Timo Sirainen <varlistentry>
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainen An unexpected failure occurred, and retrying the request
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen is pointless.
1b3bb8d39686ed24730cbc31cc9a33dc62c8c6c3Timo Sirainen </varlistentry>
ace3c14e47a5a865df8aeea2fabc993b609dd163Timo Sirainen </variablelist>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
41bb0aa8e357876bc9a1916a37c9e3e78e5f8185Timo Sirainen </citerefentry>
dd8de60250511cc729b67249e61dfc6b4debff11Timo Sirainen translates these error codes to suitable error messages.
dd8de60250511cc729b67249e61dfc6b4debff11Timo Sirainen </refsection>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <refsection><info><title>SEE ALSO</title></info>
1cad0dd34667548ba39f794ddeb9fc486cf4c666Timo Sirainen </citerefentry>,
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <citerefentry>
abfcd9f73b9ad1eeef4fe6e9940383defabf68c3Timo Sirainen <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen </citerefentry>,
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <citerefentry>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
cd5ee8630497fdbd853ef588a858b4ef619a5e03Timo Sirainen </citerefentry>,
7394389230750c45b105cdefb5850c81cae8cdc0Timo Sirainen <citerefentry>
e06c0b65c16ccce69bbee009ead14d7d3d17a256Timo Sirainen <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
5a07b37a9df398b5189c14872a600384208ab74bTimo Sirainen </citerefentry>,
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <citerefentry>
16c89b1260c9d07c01c83a9219424d3727069b2eTimo Sirainen <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
659fe5d24825b160cae512538088020d97a60239Timo Sirainen </citerefentry>,
9887c39c5ba429169389153ca99de49e084a73f0Timo Sirainen <citerefentry>
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen </citerefentry>.
03dbd273251103f745c08966f1809c02870390ffTimo Sirainen </refsection>