lwres_getipnode.docbook revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
71092d70af35567dd154d3de2ce04ce62e157a7cLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
7c66aeba0f28cb82027d6015405ed71afa3b6059Kay Sievers - Copyright (C) 2001 Internet Software Consortium.
c904f64d84db8c4eebedf210ba10893f19ba05edLennart Poettering - Permission to use, copy, modify, and distribute this software for any
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers - purpose with or without fee is hereby granted, provided that the above
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers - copyright notice and this permission notice appear in all copies.
f957632b960a0a42999b38ded7089fa602b41745Kay Sievers - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
9a36607584bbd1d78775353e022a51794b4e27b1Lennart Poettering - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
9a36607584bbd1d78775353e022a51794b4e27b1Lennart Poettering - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
a40593a0d0d740efa387e35411e1e456a6c5aba7Lennart Poettering - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
20ffc4c4a9226b0e45cc02ad9c0108981626c0bbKay Sievers - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
26306aed13e73b6edbc4b3fd7b97e421e152b56bKay Sievers - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
26306aed13e73b6edbc4b3fd7b97e421e152b56bKay Sievers - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
26306aed13e73b6edbc4b3fd7b97e421e152b56bKay Sievers - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
26306aed13e73b6edbc4b3fd7b97e421e152b56bKay Sievers<!-- $Id: lwres_getipnode.docbook,v 1.3 2001/04/24 18:11:13 gson Exp $ -->
466784c8710e5cb0e0b86a16506d992d7ec5b619Kay Sievers<refentryinfo>
a4cc3e5ccc0a3033d764a9eb3ae5ee90db560682Lennart Poettering</refentryinfo>
a4cc3e5ccc0a3033d764a9eb3ae5ee90db560682Lennart Poettering<refentrytitle>lwres_getipnode</refentrytitle>
466784c8710e5cb0e0b86a16506d992d7ec5b619Kay Sievers<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<refsynopsisdiv>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<funcprototype>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poetteringstruct hostent *
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<function>lwres_getipnodebyname</function></funcdef>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering</funcprototype>
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<funcprototype>
049b4474b35d0b854f87b0795a5113665413f6a4Lennart Poetteringstruct hostent *
bafb15bab99887d1b6b8a35136531bac6c3876a6Lennart Poettering<function>lwres_getipnodebyaddr</function></funcdef>
eb124a97fb72d076014253b1acde69d428f15ecfLennart Poettering</funcprototype>
154ff088d371bee5651eaa2bc9bde8a34c185656Lennart Poettering<funcprototype>
e1b7e7ec9b34ae6ae54a4c8084395cbf2bfe9960Lennart Poettering<function>lwres_freehostent</function></funcdef>
c3bb87dbab8b79bb9253407cb5b7f3e6fe8db395Lennart Poettering</funcprototype>
e7256c5c137e58fb3dc1ebca8e5845733a5f733cLennart Poettering</funcsynopsis>
e7256c5c137e58fb3dc1ebca8e5845733a5f733cLennart Poettering</refsynopsisdiv>
18d4e7c26e7806ac363d19989df7144d5058ce41Lennart PoetteringThese functions perform thread safe, protocol independent
36c0868b67a9387d39c97983d3d22cfce0fedc62Lennart Poetteringnodename-to-address and address-to-nodename
36c0868b67a9387d39c97983d3d22cfce0fedc62Lennart Poetteringtranslation as defined in RFC2553.
c5757cc8dbcddb3e8b13ebba4ea4b36589bfd3dbLennart Poetteringwhich is defined in
c5757cc8dbcddb3e8b13ebba4ea4b36589bfd3dbLennart Poettering<programlisting>
d907c2086716681936755f28ac80b3445c6d0196Lennart Poettering char *h_name; /* official name of host */
d907c2086716681936755f28ac80b3445c6d0196Lennart Poettering char **h_aliases; /* alias list */
d907c2086716681936755f28ac80b3445c6d0196Lennart Poettering int h_addrtype; /* host address type */
d907c2086716681936755f28ac80b3445c6d0196Lennart Poettering int h_length; /* length of address */
d907c2086716681936755f28ac80b3445c6d0196Lennart Poettering char **h_addr_list; /* list of addresses from name server */
049b4474b35d0b854f87b0795a5113665413f6a4Lennart Poettering#define h_addr h_addr_list[0] /* address, for backward compatibility */
bdeeb6b543a2a2d0a494f17b85f1498859cdfc2fLennart Poettering</programlisting>
bdeeb6b543a2a2d0a494f17b85f1498859cdfc2fLennart PoetteringThe members of this structure are:
bdeeb6b543a2a2d0a494f17b85f1498859cdfc2fLennart Poettering<varlistentry><term><constant>h_name</constant></term>
bdeeb6b543a2a2d0a494f17b85f1498859cdfc2fLennart PoetteringThe official (canonical) name of the host.
174da5c5cabbaf3f3a8fc1f14bd6a3b50b2ea278Lennart Poettering<varlistentry><term><constant>h_aliases</constant></term>
fb6becb4436ae4078337011b2017ce294e7361cfLennart PoetteringA NULL-terminated array of alternate names (nicknames) for the host.
6c12b52e19640747e96f89d85422941a23dc6b29Lennart Poettering<varlistentry><term><constant>h_addrtype</constant></term>
7041efe9600e569da6089c36d00fa3ff58e33178Lennart PoetteringThe type of address being returned - usually
9444b1f20e311f073864d81e913bd4f32fe95cfdLennart Poettering<varlistentry><term><constant>h_length</constant></term>
69af45035913e7119cffd94c542bd3039600e45dZbigniew Jędrzejewski-SzmekThe length of the address in bytes.
466784c8710e5cb0e0b86a16506d992d7ec5b619Kay Sievers<varlistentry><term><constant>h_addr_list</constant></term>
a016b9228f338cb9b380ce7e00826ef462767d98Lennart Poetteringterminated array of network addresses for the host.
a016b9228f338cb9b380ce7e00826ef462767d98Lennart PoetteringHost addresses are returned in network byte order.
1f263d4dc23b9807ac6138eb5014d3d94c5fe51aLennart Poettering</variablelist>
1f263d4dc23b9807ac6138eb5014d3d94c5fe51aLennart Poettering<function>lwres_getipnodebyname()</function>
1f263d4dc23b9807ac6138eb5014d3d94c5fe51aLennart Poetteringlooks up addresses of protocol family
4e09014daf8f98584b3f15e64e93bed232e70a6bLennart Poetteringfor the hostname
4e09014daf8f98584b3f15e64e93bed232e70a6bLennart Poetteringparameter contains ORed flag bits to
4e09014daf8f98584b3f15e64e93bed232e70a6bLennart Poetteringspecify the types of addresses that are searched
4e09014daf8f98584b3f15e64e93bed232e70a6bLennart Poetteringfor, and the types of addresses that are returned.
4e09014daf8f98584b3f15e64e93bed232e70a6bLennart PoetteringThe flag bits are:
eb01ba5de14859d7a94835ab9299de40132d549aLennart Poettering<varlistentry><term><constant>AI_V4MAPPED</constant></term>
eb01ba5de14859d7a94835ab9299de40132d549aLennart PoetteringThis is used with an
eb01ba5de14859d7a94835ab9299de40132d549aLennart Poetteringof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
eb01ba5de14859d7a94835ab9299de40132d549aLennart PoetteringIPv6 addresses.
e4ee6e5cc3e8e23e1ecc0d9fa756d9cc2534d218Lennart Poettering<varlistentry><term><constant>AI_ALL</constant></term>
86312ab8de59c1066d6d2b456f3a9106ce3e0991Lennart PoetteringThis is used with an
86312ab8de59c1066d6d2b456f3a9106ce3e0991Lennart Poetteringof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
86312ab8de59c1066d6d2b456f3a9106ce3e0991Lennart PoetteringIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
86312ab8de59c1066d6d2b456f3a9106ce3e0991Lennart PoetteringIPv6 addresses.
154ff088d371bee5651eaa2bc9bde8a34c185656Lennart Poettering<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
7e853a9b9a858edbc24e6c85d134478cec840173Lennart PoetteringOnly return an IPv6 or IPv4 address if here is an active network
7e853a9b9a858edbc24e6c85d134478cec840173Lennart Poetteringinterface of that type. This is not currently implemented
7e853a9b9a858edbc24e6c85d134478cec840173Lennart Poetteringin the BIND 9 lightweight resolver, and the flag is ignored.
d686f034c3b9021e07faefe172ee660abd952871Lennart Poettering<varlistentry><term><constant>AI_DEFAULT</constant></term>
69af45035913e7119cffd94c542bd3039600e45dZbigniew Jędrzejewski-SzmekThis default sets the
ab8e074ce25b9947314c69e17afe1bd2527ee26dLennart Poettering</variablelist>
ab8e074ce25b9947314c69e17afe1bd2527ee26dLennart Poettering<function>lwres_getipnodebyaddr()</function>
ab8e074ce25b9947314c69e17afe1bd2527ee26dLennart Poetteringperforms a reverse lookup
b454b11220e87add6d0f011695c7912b009c853dLennart Poetteringdenotes the protocol family, typically
fff87a35d9e26c0d4ea41273a963c0eb20e18da4Zbigniew Jędrzejewski-Szmekreleases all the memory associated with
b8b4d3dddc7611dce3bf28004b0375d661120c62Lennart PoetteringAny memory allocated for the
b5c03638d48c07aa0eaf13b5f54000c7133e1883Lennart Poetteringis freed, as is the memory for the
b5c03638d48c07aa0eaf13b5f54000c7133e1883Lennart Poetteringstructure itself.
eece8c6fb5f4d354dcef6fd369e876c4f3a3f163Lennart PoetteringIf an error occurs,
356ce9915ab1a4a1e6dc26954df34936a69e7c12Lennart Poettering<function>lwres_getipnodebyname()</function>
356ce9915ab1a4a1e6dc26954df34936a69e7c12Lennart Poettering<function>lwres_getipnodebyaddr()</function>
3b953d68c628c6ae70adba871719ac0f16083b51Josh Triplettto an approriate error code and the function returns a
3b953d68c628c6ae70adba871719ac0f16083b51Josh TriplettThe error codes and their meanings are defined in
09f727eebd87661f263d3c2c1e0de7b7771acd40Lennart Poettering<filename><lwres/netdb.h></filename>:
09f727eebd87661f263d3c2c1e0de7b7771acd40Lennart Poettering<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
795607b22308f5b92073b012e43be1892fdd97c0Lennart PoetteringNo such host is known.
795607b22308f5b92073b012e43be1892fdd97c0Lennart Poettering<varlistentry><term><constant>NO_ADDRESS</constant></term>
0be8342c04bbf129b4a21e5073eacccbbce4e896Lennart PoetteringThe server recognised the request and the name but no address is
0be8342c04bbf129b4a21e5073eacccbbce4e896Lennart Poetteringavailable. Another type of request to the name server for the
0be8342c04bbf129b4a21e5073eacccbbce4e896Lennart Poetteringdomain might return an answer.
487060c2394b7703e59650ef332053645ffae2a3Lennart Poettering<varlistentry><term><constant>TRY_AGAIN</constant></term>
826872b61e4857dfffe63ba84e2b005623baecd6Lennart PoetteringA temporary and possibly transient error occurred, such as a
826872b61e4857dfffe63ba84e2b005623baecd6Lennart Poetteringfailure of a server to respond. The request may succeed if
3679d1126bae52e02f6cd60fca196f616b9e660dLennart Poettering<varlistentry><term><constant>NO_RECOVERY</constant></term>
3679d1126bae52e02f6cd60fca196f616b9e660dLennart PoetteringAn unexpected failure occurred, and retrying the request
3679d1126bae52e02f6cd60fca196f616b9e660dLennart Poettering<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
3679d1126bae52e02f6cd60fca196f616b9e660dLennart Poettering</citerefentry>
3679d1126bae52e02f6cd60fca196f616b9e660dLennart Poetteringtranslates these error codes to suitable error messages.
3679d1126bae52e02f6cd60fca196f616b9e660dLennart Poettering</citerefentry>,
cbb7712189527f9f483321607e44c4ead3dd11b8Lennart Poettering<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
d01a73b6396f57792113c1b5df6e8492fc703e5eLennart Poettering</citerefentry>,
f8aeee1f1fe432924b355f48f01f09c9a552ed97Lennart Poettering<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
f8aeee1f1fe432924b355f48f01f09c9a552ed97Lennart Poettering</citerefentry>,
f8aeee1f1fe432924b355f48f01f09c9a552ed97Lennart Poettering<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
f8aeee1f1fe432924b355f48f01f09c9a552ed97Lennart Poettering</citerefentry>,
490b7e47093d491a2bdb1084fe92b796f4e07eefLennart Poettering<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
81d112a8f0522a09fcfe317f420363a2b728137cLennart Poettering</citerefentry>,
b44be3ecf6326c27aa2c6c6d1fe34e22e22592a0Lennart Poettering<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
b44be3ecf6326c27aa2c6c6d1fe34e22e22592a0Lennart Poettering</citerefentry>.