lwres_getipnode.docbook revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem - Copyright (C) 2001 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and distribute this software for any
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - purpose with or without fee is hereby granted, provided that the above
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
4da61833a1cbbca94094f9653fd970582b97a72etrawick - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
4789804be088bcd86ae637a29cdb7fda25169521jailletc - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
4789804be088bcd86ae637a29cdb7fda25169521jailletc - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- $Id: lwres_getipnode.docbook,v 1.3 2001/04/24 18:11:13 gson Exp $ -->
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<refentryinfo>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic</refentryinfo>
69301145375a889e7e37caf7cc7321ac0f91801erpluem<refnamediv>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza</refnamediv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<refsynopsisdiv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsis>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf<funcprototype>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sfstruct hostent *
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic</funcprototype>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic<funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavicstruct hostent *
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcprototype>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covener<funcprototype>
44ff304057225e944e220e981d434a046d14cf06covener</funcprototype>
44ff304057225e944e220e981d434a046d14cf06covener</funcsynopsis>
44ff304057225e944e220e981d434a046d14cf06covener</refsynopsisdiv>
5d1ba75b8794925e67591c209085a49279791de9covenerThese functions perform thread safe, protocol independent
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrandnodename-to-address and address-to-nodename
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrandtranslation as defined in RFC2553.
caad2986f81ab263f7af41467dd622dc9add17f3ylavicwhich is defined in
f7317ff316c2b141feea31bddb74d5d3fa1584edjorton<programlisting>
f7317ff316c2b141feea31bddb74d5d3fa1584edjortonstruct hostent {
2165214331e4afafca4048f66f303d0253d7b001covener char *h_name; /* official name of host */
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem char **h_aliases; /* alias list */
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem int h_addrtype; /* host address type */
1e2d421a36999d292042a5539971070d54aa6c63ylavic int h_length; /* length of address */
1e2d421a36999d292042a5539971070d54aa6c63ylavic char **h_addr_list; /* list of addresses from name server */
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh#define h_addr h_addr_list[0] /* address, for backward compatibility */
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedooh</programlisting>
0b67eb8568cd58bb77082703951679b42cf098actrawickThe members of this structure are:
0b67eb8568cd58bb77082703951679b42cf098actrawick<variablelist>
0b67eb8568cd58bb77082703951679b42cf098actrawick<varlistentry><term><constant>h_name</constant></term>
09c87c777bed1655621bb20e1c46cb6b1a63279dcovenerThe official (canonical) name of the host.
3060ce7f798fbda7999cd4ddf89b525d2b294185covener<varlistentry><term><constant>h_aliases</constant></term>
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavicA NULL-terminated array of alternate names (nicknames) for the host.
e466c40e1801982602ee0200c9e8b61cc148742djailletc<varlistentry><term><constant>h_addrtype</constant></term>
457468b82e59d01eba00dd9d0817309c8f5e414ejimThe type of address being returned - usually
49dacedb6c387b786b7911082ff35121a45f414bcovener<varlistentry><term><constant>h_length</constant></term>
cfd9415521847b2f9394fad04fb701cfb955f503rjungThe length of the address in bytes.
28c31fb73c1264bd1d0ff932573677030b024c7dwrowe<varlistentry><term><constant>h_addr_list</constant></term>
63b9f1f5880391261705f696d7d65507bbe9ace3covenerterminated array of network addresses for the host.
63b9f1f5880391261705f696d7d65507bbe9ace3covenerHost addresses are returned in network byte order.
49dacedb6c387b786b7911082ff35121a45f414bcovener</variablelist>
3c990331fc6702119e4f5b8ba9eae3021aea5265jimlooks up addresses of protocol family
fc42512879dd0504532f52fe5d0d0383dda96a1eniqfor the hostname
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niqparameter contains ORed flag bits to
da0442c0440caef34706e2c2f3af05cb65921cc0jailletcspecify the types of addresses that are searched
983528026996668ea295be95aedb9c7a346af470ylavicfor, and the types of addresses that are returned.
da0442c0440caef34706e2c2f3af05cb65921cc0jailletcThe flag bits are:
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc<variablelist>
06b8f183140c8e02e0974e938a05078b511d1603covener<varlistentry><term><constant>AI_V4MAPPED</constant></term>
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluemThis is used with an
259878293a997ff49f5ddfc53d3739cbdc25444ecovenerof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
259878293a997ff49f5ddfc53d3739cbdc25444ecovenerIPv6 addresses.
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrin<varlistentry><term><constant>AI_ALL</constant></term>
65967d05f839dbf27cf91d91fa79585eeae19660minfrinThis is used with an
65967d05f839dbf27cf91d91fa79585eeae19660minfrinof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
65967d05f839dbf27cf91d91fa79585eeae19660minfrinIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
8152945ae46857b170cb227e79bb799f4fc7710dminfrinIPv6 addresses.
8152945ae46857b170cb227e79bb799f4fc7710dminfrin<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
75f5c2db254c0167a0e396254460de09b775d203trawickOnly return an IPv6 or IPv4 address if here is an active network
4f0358189bfa57b8e75bd6b94db264302a8f336amrumphinterface of that type. This is not currently implemented
4f0358189bfa57b8e75bd6b94db264302a8f336amrumphin the BIND 9 lightweight resolver, and the flag is ignored.
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawick<varlistentry><term><constant>AI_DEFAULT</constant></term>
54d750a84a175d8e338880514d440773eb986b50covenerThis default sets the
54d750a84a175d8e338880514d440773eb986b50covener</variablelist>
83b50288fa7d306324bba68832011ea08f5c7832covenerperforms a reverse lookup
2e15620d724fb8e3a5be183b917359a2fd6e9468covenerdenotes the protocol family, typically
b8efdc95bec9cf089aa1be0bfd07d46aa1137a7acovenerreleases all the memory associated with
179565be4043d7e5f9161aa75271fa0a001866d9covenerAny memory allocated for the
fce4949fb0b309a5744afcd503c6ed2d35621ee2coveneris freed, as is the memory for the
7b7430e701e9a31ce809da7c220bb8dfcf68c86etrawickstructure itself.
273e512f20f262e5e2aa8e0e83371d1929fb76adjkaluzaIf an error occurs,
993d1261a278d7322bccef219101220b7b4fb8c5jkaluzato an approriate error code and the function returns a
ba050a6f942b9fa0e81ed73437588005c569655ccovenerThe error codes and their meanings are defined in
ba050a6f942b9fa0e81ed73437588005c569655ccovener<variablelist>
ba050a6f942b9fa0e81ed73437588005c569655ccovener<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
135ddda3a989215d2bedbcf1529bfb269c3eda23niqNo such host is known.
001a44c352f89c9ec332ffd3e0a6927dcd19432chumbedooh<varlistentry><term><constant>NO_ADDRESS</constant></term>
cc5a4a08dc9783fcbc52ce86f11e01c281a43810minfrinThe server recognised the request and the name but no address is
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecoveneravailable. Another type of request to the name server for the
9b0076ddd1103e5fa9c1f9bafde4b06ce244fbaecovenerdomain might return an answer.
249d09d51808cb7981af99762c3b3736ca126cd5jkaluza<varlistentry><term><constant>TRY_AGAIN</constant></term>
56589be3d7a3e9343370df240010c6928cc78b39jkaluzaA temporary and possibly transient error occurred, such as a
56589be3d7a3e9343370df240010c6928cc78b39jkaluzafailure of a server to respond. The request may succeed if
77ca16c5676da23155311e13cee61e7eaba9fa3ejailletc<varlistentry><term><constant>NO_RECOVERY</constant></term>
f87299dab99bc04b51a6b8cad51b6795db862c0atrawickAn unexpected failure occurred, and retrying the request
f87299dab99bc04b51a6b8cad51b6795db862c0atrawickis pointless.
4d12805e6c18253040223ea637acd6b3b3c18f60jorton</variablelist>
e5d909f2b06bd880fb3675cd49363df981caa631trawick<citerefentry>
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener</manvolnum>
a4df2cd1e1391575a327c2a90ba4315f805a0a78covener</citerefentry>
cb666b29f81df1d11d65002250153353568021fccovenertranslates these error codes to suitable error messages.
75a230a728338d84dcfe81edd375352f34de22d0covener<citerefentry>
75a230a728338d84dcfe81edd375352f34de22d0covener</citerefentry>,
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener<citerefentry>
1f50dc34ae069adeed20b2986e5ffdefa5c410e0covener<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
63a5ea80bddcc84a462e40f402b4f330e0e05411covener</citerefentry>,
63a5ea80bddcc84a462e40f402b4f330e0e05411covener<citerefentry>
63a5ea80bddcc84a462e40f402b4f330e0e05411covener<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
65a4e663b82f8bce28ac22ab2edfd7502de36998sf</citerefentry>,
65a4e663b82f8bce28ac22ab2edfd7502de36998sf<citerefentry>
65a4e663b82f8bce28ac22ab2edfd7502de36998sf<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
c7de1955eb0eaeabf7042902476397692672d549sf</citerefentry>,
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin<citerefentry>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
74e7f6c55fd67b10cb400b3f6d1dc718a303d944minfrin</citerefentry>,
a511a29faf2ff7ead3b67680154a624effb31aafminfrin<citerefentry>
a511a29faf2ff7ead3b67680154a624effb31aafminfrin<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
a511a29faf2ff7ead3b67680154a624effb31aafminfrin</citerefentry>.