lwres_getipnode.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
19558a04decde0e7261d489d92d04ad88104217bTinderbox User - Permission to use, copy, modify, and/or distribute this software for any
2fee8782a6fd57d86a67949092ab9197111af390Evan Hunt - purpose with or without fee is hereby granted, provided that the above
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - copyright notice and this permission notice appear in all copies.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f4ee48be3994797a8332b86c101db4d7b54799ceTinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - PERFORMANCE OF THIS SOFTWARE.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<!-- Converted by db4-upgrade version 1.0 -->
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <refentryinfo>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </refentryinfo>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </copyright>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </copyright>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refnamediv>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refpurpose>lightweight resolver nodename / address translation API</refpurpose>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </refnamediv>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt <refsynopsisdiv>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <funcsynopsis>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsstruct hostent *
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater<function>lwres_getipnodebyname</function></funcdef>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <paramdef>const char *<parameter>name</parameter></paramdef>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <paramdef>int <parameter>af</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>int <parameter>flags</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>int *<parameter>error_num</parameter></paramdef>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater </funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<funcprototype>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Huntstruct hostent *
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<function>lwres_getipnodebyaddr</function></funcdef>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <paramdef>const void *<parameter>src</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>size_t <parameter>len</parameter></paramdef>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews <paramdef>int <parameter>af</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>int *<parameter>error_num</parameter></paramdef>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </funcprototype>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<funcprototype>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<function>lwres_freehostent</function></funcdef>
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews <paramdef>struct hostent *<parameter>he</parameter></paramdef>
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews </funcprototype>
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews</funcsynopsis>
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews </refsynopsisdiv>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt <refsection><info><title>DESCRIPTION</title></info>
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt These functions perform thread safe, protocol independent
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox User nodename-to-address and address-to-nodename
e76dfff967cfbe00f4d1540434832e4499a9cd83Tinderbox User translation as defined in RFC2553.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews which is defined in
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrewsstruct hostent {
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews char *h_name; /* official name of host */
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews char **h_aliases; /* alias list */
aef6cf0f147a5014d4891c9689b9f463399e16e7Tinderbox User int h_addrtype; /* host address type */
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews int h_length; /* length of address */
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User char **h_addr_list; /* list of addresses from name server */
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User#define h_addr h_addr_list[0] /* address, for backward compatibility */
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews</programlisting>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews The members of this structure are:
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <variablelist>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User The official (canonical) name of the host.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <varlistentry>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <term><constant>h_aliases</constant></term>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt A NULL-terminated array of alternate names (nicknames) for the
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews The type of address being returned - usually
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews The length of the address in bytes.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews </varlistentry>
7f9e2fff07b9c17e0d7a0ea7abc9304ce9d01b61Tinderbox User <varlistentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews terminated array of network addresses for the host.
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews Host addresses are returned in network byte order.
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews </varlistentry>
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User </variablelist>
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater <para><function>lwres_getipnodebyname()</function>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews looks up addresses of protocol family <parameter>af</parameter>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <parameter>flags</parameter> parameter contains ORed flag bits
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User to specify the types of addresses that are searched for, and the
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater types of addresses that are returned. The flag bits are:
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <variablelist>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User This is used with an
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt of AF_INET6, and causes IPv4 addresses to be returned as
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User IPv6 addresses.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </varlistentry>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User This is used with an
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt of AF_INET6, and causes all known addresses (IPv6 and IPv4) to
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews be returned.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User If AI_V4MAPPED is also set, the IPv4 addresses are return as
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User IPv6 addresses.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <varlistentry>
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater <term><constant>AI_ADDRCONFIG</constant></term>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt Only return an IPv6 or IPv4 address if here is an active network
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews interface of that type. This is not currently implemented
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User in the BIND 9 lightweight resolver, and the flag is ignored.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </varlistentry>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <varlistentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User This default sets the
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </variablelist>
1fce11b1d3f2d461d261156b8cdc64ab864f06a9Tinderbox User <para><function>lwres_getipnodebyaddr()</function>
fab54780409846f7c71f6026d665f18c77c649efTinderbox User performs a reverse lookup of address <parameter>src</parameter>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews which is <parameter>len</parameter> bytes long.
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User <parameter>af</parameter> denotes the protocol family, typically
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews releases all the memory associated with the <type>struct
689fb19ba11ed40363cbc031d0396befdb409b89Tinderbox User hostent</type> pointer <parameter>he</parameter>. Any memory
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox User <constant>h_aliases</constant> is freed, as is the memory for
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </refsection>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refsection><info><title>RETURN VALUES</title></info>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews If an error occurs,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews to an appropriate error code and the function returns a
cdf1c3d486ec082ef6c92297d22d54a67cca0c90Tinderbox 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.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <varlistentry>
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User A temporary and possibly transient error occurred, such as a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews failure of a server to respond. The request may succeed if
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews An unexpected failure occurred, and retrying the request
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User is pointless.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </varlistentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </variablelist>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </citerefentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews translates these error codes to suitable error messages.
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User </refsection>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <refsection><info><title>SEE ALSO</title></info>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </citerefentry>,
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User <citerefentry>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt </citerefentry>,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <citerefentry>
3857cb6fcabeb79d85de4b3e3e4ab99912b701f8Mark Andrews <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews </citerefentry>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <citerefentry>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson </citerefentry>,
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <citerefentry>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </citerefentry>,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews <citerefentry>
8292deab031e7599cd7622aa7675fbe139ca6095Mark Andrews <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
c1e2310a3725eeed45e5e7c86750c64c5a02e993Francis Dupont </citerefentry>.
4b61b671f5de767ec1d1b8e6cf7b849bddf08e98Tinderbox User </refsection>