lwres_getipnode.html revision 8a66318e41ed14c5a88130e8c362610e8faa2121
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
c78c39caab4cf8b5daefc9c65878f7f5ed3eb7a0Tinderbox User - Copyright (C) 2001, 2003 Internet Software Consortium.
ab496cc3df1648e9ad992a87c35c2c0870fdc69dTinderbox User - Permission to use, copy, modify, and distribute this software for any
7c1468ed500356839a4a222517364e6ce18cb1a2Tinderbox User - purpose with or without fee is hereby granted, provided that the above
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User - copyright notice and this permission notice appear in all copies.
1f4c645185bd8fc70048e0a69eee46193a284e5cTinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews - PERFORMANCE OF THIS SOFTWARE.
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews<!-- $Id: lwres_getipnode.html,v 1.9 2004/03/05 08:32:20 marka Exp $ -->
e676a596869d8a80a644c99a848afb53d1c5975eMark Andrews>lwres_getipnode</TITLE
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserNAME="GENERATOR"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="REFENTRY"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsBGCOLOR="#FFFFFF"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserTEXT="#000000"
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark AndrewsLINK="#0000FF"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsVLINK="#840084"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserALINK="#0000FF"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>lwres_getipnode</A
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="REFNAMEDIV"
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
16f6050f29b6b0422cee858e609f65e474e70ef2Tinderbox UserCLASS="REFSYNOPSISDIV"
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt>Synopsis</H2
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic UpdaterCLASS="FUNCSYNOPSIS"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="FUNCSYNOPSISINFO"
16f6050f29b6b0422cee858e609f65e474e70ef2Tinderbox UserCLASS="FUNCDEF"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>struct hostent *
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updaterlwres_getipnodebyname</CODE
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>(const char *name, int af, int flags, int *error_num);</CODE
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="FUNCDEF"
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User>struct hostent *
2ae159b376dac23870d8005563c585acf85a4b5aEvan Huntlwres_getipnodebyaddr</CODE
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt>(const void *src, size_t len, int af, int *error_num);</CODE
2ae159b376dac23870d8005563c585acf85a4b5aEvan HuntCLASS="FUNCDEF"
2ae159b376dac23870d8005563c585acf85a4b5aEvan Huntlwres_freehostent</CODE
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt>(struct hostent *he);</CODE
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="REFSECT1"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>DESCRIPTION</H2
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>These functions perform thread safe, protocol independent
7a6494cfb6cc7d3f67af07359561e05e6bb8c0edTinderbox Usernodename-to-address and address-to-nodename
77932ac533c711eca5cd86de4e7eca8d91102b43Tinderbox Usertranslation as defined in RFC2553.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>struct hostent</SPAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewswhich is defined in
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark AndrewsCLASS="FILENAME"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PROGRAMLISTING"
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson>struct hostent {
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User char *h_name; /* official name of host */
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews char **h_aliases; /* alias list */
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User 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:
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="VARIABLELIST"
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox UserCLASS="CONSTANT"
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>The official (canonical) name of the host.</P
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="CONSTANT"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>h_aliases</TT
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>A NULL-terminated array of alternate names (nicknames) for the host.</P
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsCLASS="CONSTANT"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>h_addrtype</TT
e20788e1216ed720aefa84f3295f7899d9f28c22Mark Andrews>The type of address being returned - usually
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews>PF_INET</SPAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>PF_INET6</SPAN
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="CONSTANT"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>h_length</TT
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox User>The length of the address in bytes.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="CONSTANT"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>h_addr_list</TT
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsterminated array of network addresses for the host.
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserHost addresses are returned in network byte order.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="FUNCTION"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User>lwres_getipnodebyname()</TT
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userlooks up addresses of protocol family
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PARAMETER"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userfor the hostname
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PARAMETER"
a7c412f37cc73d0332887a746e81220cbf09dd00Mark AndrewsCLASS="PARAMETER"
933799f3641f4f78445d015008bad0038900a82aTinderbox Userparameter contains ORed flag bits to
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox Userspecify the types of addresses that are searched
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrewsfor, and the types of addresses that are returned.
7ca715ad1587a68a531ea1cdea07515d7232567eTinderbox UserThe flag bits are:
e676a596869d8a80a644c99a848afb53d1c5975eMark AndrewsCLASS="VARIABLELIST"
933799f3641f4f78445d015008bad0038900a82aTinderbox UserCLASS="CONSTANT"
4151211e6649332f7b5a55870cbe37128bcc7b29Tinderbox User>AI_V4MAPPED</TT
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater>This is used with an
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox UserCLASS="PARAMETER"
d7d105151a78d35afb4233d2a6dbd47b7ec0d9a5Tinderbox Userof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox UserIPv6 addresses.</P
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CONSTANT"
5ecad47f69b3fd945472ab2900a9ff826a7ce2f6Automatic Updater>This is used with an
91d187ce035f39073f0732ff2a401a45c3c955fbMark AndrewsCLASS="PARAMETER"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
9cd5eb6fe0f26d65724b99216cb31dcdd12e4afdAutomatic UpdaterIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox UserIPv6 addresses.</P
b02be031b9ff37b042adc8e68e36b8bbc1f672b7Tinderbox UserCLASS="CONSTANT"
0e573cdd111e060e5f6c18249b5ccacbe8abe278Tinderbox User>AI_ADDRCONFIG</TT
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>Only return an IPv6 or IPv4 address if here is an active network
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsinterface of that type. This is not currently implemented
bf5e2127e92e52cbf661e77dd6a76e5aef43542fTinderbox Userin the BIND 9 lightweight resolver, and the flag is ignored.</P
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CONSTANT"
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User>AI_DEFAULT</TT
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>This default sets the
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox UserCLASS="CONSTANT"
757ff043760e4743dda1a10e7d58349275934902Tinderbox User>AI_V4MAPPED</TT
757ff043760e4743dda1a10e7d58349275934902Tinderbox UserCLASS="CONSTANT"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater>AI_ADDRCONFIG</TT
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsflag bits.</P
757ff043760e4743dda1a10e7d58349275934902Tinderbox UserCLASS="FUNCTION"
4fe0411487e8e4401477684c0a2bac041ca7c2d5Tinderbox User>lwres_getipnodebyaddr()</TT
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox Userperforms a reverse lookup
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox UserCLASS="PARAMETER"
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserCLASS="PARAMETER"
dcad2ea9d36f03b1e5dbec881478dfa4aaed1bc0Tinderbox UserCLASS="PARAMETER"
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsdenotes the protocol family, typically
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>PF_INET</SPAN
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>PF_INET6</SPAN
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="FUNCTION"
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater>lwres_freehostent()</TT
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsreleases all the memory associated with
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater>struct hostent</SPAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="PARAMETER"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsAny memory allocated for the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark AndrewsCLASS="CONSTANT"
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark AndrewsCLASS="CONSTANT"
39cad8fb7d7ff3436bb24ce761354afcb80d295aMark Andrews>h_addr_list</TT
95c3a5e116c1da135f669c3f15398172fac6279dMark AndrewsCLASS="CONSTANT"
d7d105151a78d35afb4233d2a6dbd47b7ec0d9a5Tinderbox User>h_aliases</TT
d7d105151a78d35afb4233d2a6dbd47b7ec0d9a5Tinderbox Useris freed, as is the memory for the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>hostent</SPAN
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsstructure itself.</P
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="REFSECT1"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsNAME="AEN116"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater>RETURN VALUES</H2
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>If an error occurs,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="FUNCTION"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>lwres_getipnodebyname()</TT
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark AndrewsCLASS="FUNCTION"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>lwres_getipnodebyaddr()</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="PARAMETER"
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>*error_num</I
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsto an appropriate error code and the function returns a
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsThe error codes and their meanings are defined in
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox UserCLASS="FILENAME"
a5636b773fa05a272b6876afd99309c0b3090e2fMark AndrewsCLASS="VARIABLELIST"
bc0a4c01beede169df81a3ee5b614ed9e82339dbAutomatic UpdaterCLASS="CONSTANT"
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>HOST_NOT_FOUND</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>No such host is known.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>NO_ADDRESS</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>The server recognised the request and the name but no address is
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonavailable. Another type of request to the name server for the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtondomain might return an answer.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>TRY_AGAIN</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>A temporary and possibly transient error occurred, such as a
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonfailure of a server to respond. The request may succeed if
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>NO_RECOVERY</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>An unexpected failure occurred, and retrying the request
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonis pointless.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_hstrerror</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtontranslates these error codes to suitable error messages.</P
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="REFSECT1"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsNAME="AEN149"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>SEE ALSO</H2
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="CITEREFENTRY"
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="REFENTRYTITLE"
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="CITEREFENTRY"
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="REFENTRYTITLE"
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="CITEREFENTRY"
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="REFENTRYTITLE"
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox User>lwres_gethostent</SPAN
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="CITEREFENTRY"
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="REFENTRYTITLE"
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews>lwres_getaddrinfo</SPAN
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="CITEREFENTRY"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="REFENTRYTITLE"
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews>lwres_getnameinfo</SPAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsCLASS="CITEREFENTRY"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="REFENTRYTITLE"
febbdb34a7f7759922e239655e7429d78d3a8d26Tinderbox User>lwres_hstrerror</SPAN