lwres_getipnode.html revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater - Copyright (C) 2000, 2001 Internet Software Consortium.
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User - Permission to use, copy, modify, and distribute this software for any
a5636b773fa05a272b6876afd99309c0b3090e2fMark Andrews - purpose with or without fee is hereby granted, provided that the above
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - copyright notice and this permission notice appear in all copies.
c57668a2fbbe558c1bd21652813616f2f517c469Tinderbox User - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
5e047890ac9b745db060d95f7d1b4f876511240dTinderbox User - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
137fdbc214e99c4cbe57551e9e14f2015c2e42aeTinderbox User - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
bed0874e1a09e810575328c4bfc346a47514b69fMark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
02b47c5d62e1e827743684c28a08e871da454a2dMark Andrews - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
3cc98b8ecedcbc8465f1cf2740b966b315662430Automatic Updater>lwres_getipnode</TITLE
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsNAME="GENERATOR"
e20309353e6246485c521278131d3fced73d7957Tinderbox UserCONTENT="Modular DocBook HTML Stylesheet Version 1.61
df4ebd8217d02dafc12145b55c4d93d0255d1ec7Tinderbox UserCLASS="REFENTRY"
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark AndrewsBGCOLOR="#FFFFFF"
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic UpdaterVLINK="#840084"
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic UpdaterALINK="#0000FF"
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User>lwres_getipnode</A
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic UpdaterCLASS="REFNAMEDIV"
24934f08b9ff81c2be711e566e8002d145573031Tinderbox User>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan HuntCLASS="REFSYNOPSISDIV"
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic UpdaterCLASS="FUNCSYNOPSIS"
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox UserCLASS="FUNCSYNOPSISINFO"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="FUNCDEF"
7feccf248d2a20a2ae48b290f58ded5abc853e9aTinderbox User>struct hostent *
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewslwres_getipnodebyname</CODE
c59750de3ea3c7d5890000fb4606e8f5835a52aaTinderbox User>(const char *name, int af, int flags, int *error_num);</CODE
114f7780384371121918624ae2c80ecfce545683Tinderbox UserCLASS="FUNCDEF"
693c4232dfdffaff672197d4b9fea944c64cf80aAutomatic Updater>struct hostent *
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewslwres_getipnodebyaddr</CODE
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater>(const void *src, size_t len, int af, int *error_num);</CODE
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic UpdaterCLASS="FUNCDEF"
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updaterlwres_freehostent</CODE
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater>(struct hostent *he);</CODE
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox UserCLASS="REFSECT1"
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont>DESCRIPTION</H2
2ba8f584b97cbab864570e38fd26b8cb90961428Tinderbox User>These functions perform thread safe, protocol independent
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox Usernodename-to-address and address-to-nodename
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewstranslation as defined in RFC2553.</P
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>struct hostent</SPAN
a308b69ac66fadf66863484f301314d6e6a3f1d2Automatic Updaterwhich is defined in
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="FILENAME"
b871c7156eb037d41f53828c6fcb9cc876128962Mark AndrewsCLASS="PROGRAMLISTING"
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews>struct hostent {
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews char *h_name; /* official name of host */
551271d8198ae06e37edf5da519d8ee153eeac0fTinderbox User char **h_aliases; /* alias list */
b871c7156eb037d41f53828c6fcb9cc876128962Mark Andrews int h_addrtype; /* host address type */
df4ebd8217d02dafc12145b55c4d93d0255d1ec7Tinderbox User int h_length; /* length of address */
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updater char **h_addr_list; /* list of addresses from name server */
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater#define h_addr h_addr_list[0] /* address, for backward compatibility */</PRE
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater>The members of this structure are:
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic UpdaterCLASS="VARIABLELIST"
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic UpdaterCLASS="CONSTANT"
f2770f6b39a9b2a98afb7a11ed105f73f1570c1eAutomatic Updater>The official (canonical) name of the host.</P
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox UserCLASS="CONSTANT"
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User>h_aliases</TT
c7ef13f6c9ef4436bc804b150e0a93307b11fa27Tinderbox User>A NULL-terminated array of alternate names (nicknames) for the host.</P
d642d3857129678797a01adee14fbd70335b05a9Mark AndrewsCLASS="CONSTANT"
609b8d08176469485edce25f3c2f50365bbd3819Mark Andrews>h_addrtype</TT
8e5fce1f9ceba17dd7e3ff0eb287e1e999c14249Mark Andrews>The type of address being returned - usually
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox User>PF_INET6</SPAN
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CONSTANT"
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater>The length of the address in bytes.</P
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CONSTANT"
19b3dc94bce93fa76bd7e066f9298630dbc9dcb4Automatic Updater>h_addr_list</TT
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox Userterminated array of network addresses for the host.
6a9d2121152c94cb9e35832126c3f2e4d18d81edTinderbox UserHost addresses are returned in network byte order.</P
4cda4fd158d6ded5586bacea8c388445d99611eaAutomatic UpdaterCLASS="FUNCTION"
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews>lwres_getipnodebyname()</TT
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updaterlooks up addresses of protocol family
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="PARAMETER"
551271d8198ae06e37edf5da519d8ee153eeac0fTinderbox Userfor the hostname
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="PARAMETER"
dc5552b4df5e3821783821c8d4e734c1608c446eTinderbox UserCLASS="PARAMETER"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updaterparameter contains ORed flag bits to
cf7e98f59148b559946a7f1ca728471374f1eef3Automatic Updaterspecify the types of addresses that are searched
c3fd32ed29e9e419bb56583f4272a506773b1ea0Automatic Updaterfor, and the types of addresses that are returned.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas GustafssonThe flag bits are:
fe600c3ad88c0bb078283a953d048087d227c0e5Tinderbox UserCLASS="VARIABLELIST"
3857cb6fcabeb79d85de4b3e3e4ab99912b701f8Mark AndrewsCLASS="CONSTANT"
d642d3857129678797a01adee14fbd70335b05a9Mark Andrews>AI_V4MAPPED</TT
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson>This is used with an
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox UserCLASS="PARAMETER"
e31cfd80616deb9781902306b34a69aa7309b6cbTinderbox Userof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
e31cfd80616deb9781902306b34a69aa7309b6cbTinderbox UserIPv6 addresses.</P
7d12a6b412fe47e6d6582923fd6954ab8cd0baebAutomatic UpdaterCLASS="CONSTANT"
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews>This is used with an
3351ccbd5c1961404044f8273d54dad405f53960Mark AndrewsCLASS="PARAMETER"
0b57424d28c9a67018107133f9fbc0a7dcf057e2Mark Andrewsof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic UpdaterIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic UpdaterIPv6 addresses.</P
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic UpdaterCLASS="CONSTANT"
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updater>AI_ADDRCONFIG</TT
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews>Only return an IPv6 or IPv4 address if here is an active network
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox Userinterface of that type. This is not currently implemented
82a986aaa5d3384a541b5a7d6dae8cf0726d6513Tinderbox Userin the BIND 9 lightweight resolver, and the flag is ignored.</P
dc435f1033bcba88b748074987db6cfd34c057a4Tinderbox UserCLASS="CONSTANT"
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews>AI_DEFAULT</TT
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User>This default sets the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="CONSTANT"
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User>AI_V4MAPPED</TT
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsCLASS="CONSTANT"
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User>AI_ADDRCONFIG</TT
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox UserCLASS="FUNCTION"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_getipnodebyaddr()</TT
e20309353e6246485c521278131d3fced73d7957Tinderbox Userperforms a reverse lookup
b13d89bd89878137c81b36a36596cca3920f27a4Automatic UpdaterCLASS="PARAMETER"
a5636b773fa05a272b6876afd99309c0b3090e2fMark AndrewsCLASS="PARAMETER"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="PARAMETER"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtondenotes the protocol family, typically
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>PF_INET</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>PF_INET6</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="FUNCTION"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_freehostent()</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonreleases all the memory associated with
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>struct hostent</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="PARAMETER"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonAny memory allocated for the
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>h_addr_list</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CONSTANT"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>h_aliases</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonis freed, as is the memory for the
ae7e54b14c946e0984c191554db9abb4893f9349Automatic Updaterstructure itself.</P
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="REFSECT1"
ae7e54b14c946e0984c191554db9abb4893f9349Automatic Updater>RETURN VALUES</H2
ae7e54b14c946e0984c191554db9abb4893f9349Automatic Updater>If an error occurs,
ae7e54b14c946e0984c191554db9abb4893f9349Automatic UpdaterCLASS="FUNCTION"
b30ec46fec40a1b246f7965fbcd341fc6cfd1cc1Mark Andrews>lwres_getipnodebyname()</TT
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="FUNCTION"
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox User>lwres_getipnodebyaddr()</TT
c11c7b47726c02eb05e29ff7be56a3343146e396Tinderbox UserCLASS="PARAMETER"
02b47c5d62e1e827743684c28a08e871da454a2dMark Andrews>*error_num</I
099b86fb8136a7dff81df85cf395978c16eb254cAutomatic Updaterto an approriate error code and the function returns a
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterThe error codes and their meanings are defined in
febbdb34a7f7759922e239655e7429d78d3a8d26Tinderbox UserCLASS="FILENAME"
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox UserCLASS="VARIABLELIST"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CONSTANT"
3de6db3208d51de1e138b63b9670430c03f99694Automatic Updater>HOST_NOT_FOUND</TT
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User>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
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews>A temporary and possibly transient error occurred, such as a
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonfailure of a server to respond. The request may succeed if
a26b22914b7bf25f065afb8cdef983766dcd672bAutomatic UpdaterCLASS="CONSTANT"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater>NO_RECOVERY</TT
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>An unexpected failure occurred, and retrying the request
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrewsis pointless.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
b7aab05edae933e169d5f83c653935b17c7f0a8bMark Andrews>lwres_hstrerror</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtontranslates these error codes to suitable error messages.</P
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFSECT1"
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark AndrewsNAME="AEN149"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>RFC2553</SPAN
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="CITEREFENTRY"
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox UserCLASS="REFENTRYTITLE"
56effd2e3f579fd77b1fb37d47871d1bf1286bc4Automatic UpdaterCLASS="CITEREFENTRY"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic UpdaterCLASS="REFENTRYTITLE"
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater>lwres_gethostent</SPAN
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark AndrewsCLASS="CITEREFENTRY"
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark AndrewsCLASS="REFENTRYTITLE"
7adcb4de92bf4383a4c5624c4ed256736d02bc6dMark Andrews>lwres_getaddrinfo</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington>lwres_getnameinfo</SPAN
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="CITEREFENTRY"
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonCLASS="REFENTRYTITLE"
409ba95e573b40cf36acf97dd62ee7e9c7775851Tinderbox User>lwres_hstrerror</SPAN