lwres_getipnode.html revision 3970098dcd2a7122541667b4b56cea8abce8ccf2
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Hunt - Copyright (C) 2000, 2001 Internet Software Consortium.
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User - Permission to use, copy, modify, and distribute this software for any
19558a04decde0e7261d489d92d04ad88104217bTinderbox User - purpose with or without fee is hereby granted, provided that the above
2fee8782a6fd57d86a67949092ab9197111af390Evan Hunt - copyright notice and this permission notice appear in all copies.
969eaf7df8ac651946f76b6631ff5db568c11ef6Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
f4ee48be3994797a8332b86c101db4d7b54799ceTinderbox User - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>lwres_getipnode</TITLE
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsNAME="GENERATOR"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="REFENTRY"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsBGCOLOR="#FFFFFF"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserTEXT="#000000"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsLINK="#0000FF"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserVLINK="#840084"
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsALINK="#0000FF"
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews>lwres_getipnode</A
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="REFNAMEDIV"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="REFSYNOPSISDIV"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>Synopsis</H2
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="FUNCSYNOPSIS"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="FUNCSYNOPSISINFO"
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan HuntCLASS="FUNCDEF"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>struct hostent *
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewslwres_getipnodebyname</CODE
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater>(const char *name, int af, int flags, int *error_num);</CODE
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="FUNCDEF"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>struct hostent *
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrewslwres_getipnodebyaddr</CODE
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>(const void *src, size_t len, int af, int *error_num);</CODE
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="FUNCDEF"
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrewslwres_freehostent</CODE
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews>(struct hostent *he);</CODE
2ae159b376dac23870d8005563c585acf85a4b5aEvan HuntCLASS="REFSECT1"
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User>DESCRIPTION</H2
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User>These functions perform thread safe, protocol independent
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsnodename-to-address and address-to-nodename
8f4e6ea383aa9a953c0adb5be6c4d8dc8dbd5c4aWitold Krecickitranslation as defined in RFC2553.</P
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>struct hostent</SPAN
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewswhich is defined in
91216cff91b34c9ff6e846dc23f248219cafe660Andreas GustafssonCLASS="FILENAME"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="PROGRAMLISTING"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>struct hostent {
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews char *h_name; /* official name of host */
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews char **h_aliases; /* alias list */
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt int h_addrtype; /* host address type */
0eb371ca0dab50ae3462e98794a6126198c52f4bMark 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 */</PRE
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>The members of this structure are:
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsCLASS="VARIABLELIST"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews>The official (canonical) name of the host.</P
2a31bd531072824ef252c18303859d6af7451b00Francis DupontCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>h_aliases</TT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>A NULL-terminated array of alternate names (nicknames) for the host.</P
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>h_addrtype</TT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>The type of address being returned - usually
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User>PF_INET</SPAN
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>PF_INET6</SPAN
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic UpdaterCLASS="CONSTANT"
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews>h_length</TT
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater>The length of the address in bytes.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="CONSTANT"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>h_addr_list</TT
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsterminated array of network addresses for the host.
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan HuntHost addresses are returned in network byte order.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="FUNCTION"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>lwres_getipnodebyname()</TT
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userlooks up addresses of protocol family
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan HuntCLASS="PARAMETER"
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Huntfor the hostname
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PARAMETER"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PARAMETER"
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox Userparameter contains ORed flag bits to
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox Userspecify the types of addresses that are searched
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox Userfor, and the types of addresses that are returned.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThe flag bits are:
fab54780409846f7c71f6026d665f18c77c649efTinderbox UserCLASS="VARIABLELIST"
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox UserCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>AI_V4MAPPED</TT
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark Andrews>This is used with an
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="PARAMETER"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsIPv6 addresses.</P
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox UserCLASS="CONSTANT"
cdf1c3d486ec082ef6c92297d22d54a67cca0c90Tinderbox User>This is used with an
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="PARAMETER"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsIPv6 addresses.</P
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>AI_ADDRCONFIG</TT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>Only return an IPv6 or IPv4 address if here is an active network
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsinterface of that type. This is not currently implemented
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsin the BIND 9 lightweight resolver, and the flag is ignored.</P
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox User>AI_DEFAULT</TT
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>This default sets the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>AI_V4MAPPED</TT
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox UserCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>AI_ADDRCONFIG</TT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsflag bits.</P
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox UserCLASS="FUNCTION"
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User>lwres_getipnodebyaddr()</TT
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox Userperforms a reverse lookup
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="PARAMETER"
3857cb6fcabeb79d85de4b3e3e4ab99912b701f8Mark AndrewsCLASS="PARAMETER"
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsCLASS="PARAMETER"
8292deab031e7599cd7622aa7675fbe139ca6095Mark Andrewsdenotes the protocol family, typically
4b61b671f5de767ec1d1b8e6cf7b849bddf08e98Tinderbox User>PF_INET</SPAN
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>PF_INET6</SPAN
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsCLASS="FUNCTION"
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>lwres_freehostent()</TT
f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Huntreleases all the memory associated with
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>struct hostent</SPAN
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="PARAMETER"
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsAny memory allocated for the
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan HuntCLASS="CONSTANT"
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsCLASS="CONSTANT"
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt>h_addr_list</TT
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="CONSTANT"
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews>h_aliases</TT
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsis freed, as is the memory for the
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews>hostent</SPAN
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrewsstructure itself.</P
ab833877278ad5535eef57e4f62291becaea5bc5Mark AndrewsCLASS="REFSECT1"
168cf0ede1cf13a095e48af6749d88fbc432f096Evan HuntNAME="AEN116"
3bd8b5a8fb126e45c67ff53b68183c889cc27918Tinderbox User>RETURN VALUES</H2
ab833877278ad5535eef57e4f62291becaea5bc5Mark Andrews>If an error occurs,
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark AndrewsCLASS="FUNCTION"
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrews>lwres_getipnodebyname()</TT
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark AndrewsCLASS="FUNCTION"
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrews>lwres_getipnodebyaddr()</TT
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark AndrewsCLASS="PARAMETER"
bcfc5188be220e1334218dfe638dffce4744e792Tinderbox User>*error_num</I
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark Andrewsto an appropriate error code and the function returns a
ab833877278ad5535eef57e4f62291becaea5bc5Mark AndrewsThe error codes and their meanings are defined in
3bd8b5a8fb126e45c67ff53b68183c889cc27918Tinderbox UserCLASS="FILENAME"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="VARIABLELIST"
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark AndrewsCLASS="CONSTANT"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>HOST_NOT_FOUND</TT
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson>No such host is known.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="CONSTANT"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>NO_ADDRESS</TT
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>The server recognised the request and the name but no address is
3a988722ad9e209ba4064604d482dc4efe0e19ebTinderbox Useravailable. Another type of request to the name server for the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtondomain might return an answer.</P
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>TRY_AGAIN</TT
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews>A temporary and possibly transient error occurred, such as a
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Huntfailure of a server to respond. The request may succeed if
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCLASS="CONSTANT"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>NO_RECOVERY</TT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>An unexpected failure occurred, and retrying the request
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsis pointless.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_hstrerror</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtontranslates these error codes to suitable error messages.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFSECT1"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>RFC2553</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_gethostent</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_getaddrinfo</SPAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="CITEREFENTRY"
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan HuntCLASS="REFENTRYTITLE"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>lwres_getnameinfo</SPAN
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="CITEREFENTRY"
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="REFENTRYTITLE"
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews>lwres_hstrerror</SPAN