lwres_getipnode.docbook revision 83a28ca274521e15086fc39febde507bcc4e145e
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt - Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
c7fd128f8ea8a527fe27c1b95ab46df7155bc8e4Tinderbox User - This Source Code Form is subject to the terms of the Mozilla Public
c7fd128f8ea8a527fe27c1b95ab46df7155bc8e4Tinderbox User - License, v. 2.0. If a copy of the MPL was not distributed with this
ba9e87b35e561bc7354ce3f4b9685b747b7be507Tinderbox User - file, You can obtain one at http://mozilla.org/MPL/2.0/.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<!-- Converted by db4-upgrade version 1.0 -->
1f9754245cbd5eec2d2a667bb292f62f72386d4bMark Andrews<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
1ca2cf024391992fe14b2df7d3ae0f575d074452Evan Hunt <refentryinfo>
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </refentryinfo>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </copyright>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </refnamediv>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <refsynopsisdiv>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <funcsynopsis>
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<funcprototype>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsstruct hostent *
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<function>lwres_getipnodebyname</function></funcdef>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt <paramdef>const char *<parameter>name</parameter></paramdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>int <parameter>af</parameter></paramdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>int <parameter>flags</parameter></paramdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>int *<parameter>error_num</parameter></paramdef>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt </funcprototype>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<funcprototype>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Huntstruct hostent *
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<function>lwres_getipnodebyaddr</function></funcdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>const void *<parameter>src</parameter></paramdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>size_t <parameter>len</parameter></paramdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>int <parameter>af</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>int *<parameter>error_num</parameter></paramdef>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater </funcprototype>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<function>lwres_freehostent</function></funcdef>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <paramdef>struct hostent *<parameter>he</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </funcprototype>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews</funcsynopsis>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User </refsynopsisdiv>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refsection><info><title>DESCRIPTION</title></info>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews These functions perform thread safe, protocol independent
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User nodename-to-address and address-to-nodename
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews translation as defined in RFC2553.
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews which is defined in
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsstruct hostent {
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User char *h_name; /* official name of host */
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt char **h_aliases; /* alias list */
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox User int h_addrtype; /* host address type */
3ccf87473f7cf6d9faac156df38a935a238f96fdTinderbox User int h_length; /* length of address */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews char **h_addr_list; /* list of addresses from name server */
551e6d2414c4f47d58a9bb0b37f206f915a4f5acTinderbox User#define h_addr h_addr_list[0] /* address, for backward compatibility */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews</programlisting>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User The members of this structure are:
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <variablelist>
51aeb0ae19596e99b029cfa933e73b76ebec480aTinderbox User <varlistentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The official (canonical) name of the host.
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </varlistentry>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <varlistentry>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews A NULL-terminated array of alternate names (nicknames) for the
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </varlistentry>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <varlistentry>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The type of address being returned - usually
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews The length of the address in bytes.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews <varlistentry>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <term><constant>h_addr_list</constant></term>
51aeb0ae19596e99b029cfa933e73b76ebec480aTinderbox User terminated array of network addresses for the host.
baeaed18341c015e9ad54ffa21973184c1bc432bMark Andrews Host addresses are returned in network byte order.
33b0d10552ea5f7716385b2cedff64daa1486c50Tinderbox User </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </variablelist>
33b0d10552ea5f7716385b2cedff64daa1486c50Tinderbox User <para><function>lwres_getipnodebyname()</function>
b378314925e78f21853a98cec924788ce1822c6cTinderbox User looks up addresses of protocol family <parameter>af</parameter>
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews for the hostname <parameter>name</parameter>. The
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <parameter>flags</parameter> parameter contains ORed flag bits
2b7254075b883d70852a2757210793603085a0f1Tinderbox User to specify the types of addresses that are searched for, and the
66317da170ed35b08f5847db2d48b225826327cbTinderbox User types of addresses that are returned. The flag bits are:
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews <variablelist>
b625bdae12277225b076a002dd4af80902529181Tinderbox User <varlistentry>
33b0d10552ea5f7716385b2cedff64daa1486c50Tinderbox User This is used with an
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater of AF_INET6, and causes IPv4 addresses to be returned as
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User IPv6 addresses.
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater </varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews This is used with an
415d630b6309922caee8469384a6fab75cf05032Mark Andrews of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews be returned.
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User If AI_V4MAPPED is also set, the IPv4 addresses are return as
415d630b6309922caee8469384a6fab75cf05032Mark Andrews IPv6 addresses.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </varlistentry>
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User <varlistentry>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <term><constant>AI_ADDRCONFIG</constant></term>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews Only return an IPv6 or IPv4 address if here is an active network
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews interface of that type. This is not currently implemented
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User in the BIND 9 lightweight resolver, and the flag is ignored.
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater </varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews This default sets the
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson </varlistentry>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews </variablelist>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <para><function>lwres_getipnodebyaddr()</function>
415d630b6309922caee8469384a6fab75cf05032Mark Andrews performs a reverse lookup of address <parameter>src</parameter>
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User which is <parameter>len</parameter> bytes long.
415d630b6309922caee8469384a6fab75cf05032Mark Andrews <parameter>af</parameter> denotes the protocol family, typically
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User releases all the memory associated with the <type>struct
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User hostent</type> pointer <parameter>he</parameter>. Any memory
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User allocated for the <constant>h_name</constant>,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <constant>h_aliases</constant> is freed, as is the memory for
1fce11b1d3f2d461d261156b8cdc64ab864f06a9Tinderbox User </refsection>
fab54780409846f7c71f6026d665f18c77c649efTinderbox User <refsection><info><title>RETURN VALUES</title></info>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews If an error occurs,
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark Andrews to an appropriate error code and the function returns a
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User The error codes and their meanings are defined in
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <variablelist>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <term><constant>HOST_NOT_FOUND</constant></term>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews No such host is known.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews The server recognised the request and the name but no address is
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews available. Another type of request to the name server for the
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews domain might return an answer.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews A temporary and possibly transient error occurred, such as a
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews failure of a server to respond. The request may succeed if
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews An unexpected failure occurred, and retrying the request
e5c7ef08d1bf9f8388de8174a47da78b9eeb7e5cTinderbox User is pointless.
2b7254075b883d70852a2757210793603085a0f1Tinderbox User </varlistentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews </variablelist>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
e5c7ef08d1bf9f8388de8174a47da78b9eeb7e5cTinderbox User </citerefentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews translates these error codes to suitable error messages.
2ca9cf1582ae972f8edc2b03bd846973b05dee6bTinderbox User </refsection>
e1ebc476b08b4a498fcf3477e42c986eb1991360Tinderbox User <refsection><info><title>SEE ALSO</title></info>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </citerefentry>,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <citerefentry>
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User </citerefentry>,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <citerefentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User </citerefentry>,
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <citerefentry>
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User </citerefentry>,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <citerefentry>
8ac5ddf659a81ed668579818981fc1a5f28405d1Tinderbox User <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox User </citerefentry>,
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt <citerefentry>
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
3ccf87473f7cf6d9faac156df38a935a238f96fdTinderbox User </citerefentry>.
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User </refsection>