lwres_getipnode.html revision 841179549b6433e782c164a562eb3422f603533d
841179549b6433e782c164a562eb3422f603533dAndreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
841179549b6433e782c164a562eb3422f603533dAndreas Gustafsson<!-- $Id: lwres_getipnode.html,v 1.5 2001/06/08 19:32:37 gson Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnode</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCONTENT="Modular DocBook HTML Stylesheet Version 1.61
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBGCOLOR="#FFFFFF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonVLINK="#840084"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonALINK="#0000FF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnode</A
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFNAMEDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSYNOPSISDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSIS"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSISINFO"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_getipnodebyname</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(const char *name, int af, int flags, int *error_num);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct hostent *
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_getipnodebyaddr</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(const void *src, size_t len, int af, int *error_num);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_freehostent</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(struct hostent *he);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>DESCRIPTION</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>These functions perform thread safe, protocol independent
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonnodename-to-address and address-to-nodename
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontranslation as defined in RFC2553.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct hostent</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FILENAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PROGRAMLISTING"
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson>struct hostent {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *h_name; /* official name of host */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **h_aliases; /* alias list */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int h_addrtype; /* host address type */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson int h_length; /* length of address */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **h_addr_list; /* list of addresses from name server */
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define h_addr h_addr_list[0] /* address, for backward compatibility */</PRE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The members of this structure are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARIABLELIST"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The official (canonical) name of the host.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>A NULL-terminated array of alternate names (nicknames) for the host.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>h_addrtype</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The type of address being returned - usually
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>PF_INET6</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The length of the address in bytes.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>h_addr_list</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonterminated array of network addresses for the host.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonHost addresses are returned in network byte order.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnodebyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlooks up addresses of protocol family
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonparameter contains ORed flag bits to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonspecify the types of addresses that are searched
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfor, and the types of addresses that are returned.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe flag bits are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARIABLELIST"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>AI_V4MAPPED</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>This is used with an
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonof AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIPv6 addresses.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>This is used with an
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonof AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIPv6 addresses.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>AI_ADDRCONFIG</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Only return an IPv6 or IPv4 address if here is an active network
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoninterface of that type. This is not currently implemented
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin the BIND 9 lightweight resolver, and the flag is ignored.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>AI_DEFAULT</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>This default sets the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>AI_V4MAPPED</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>AI_ADDRCONFIG</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnodebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms a reverse lookup
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssondenotes the protocol family, typically
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>PF_INET6</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_freehostent()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreleases all the memory associated with
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct hostent</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAny memory allocated for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>h_addr_list</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis freed, as is the memory for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure itself.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>RETURN VALUES</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>If an error occurs,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnodebyname()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getipnodebyaddr()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto an approriate error code and the function returns a
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe error codes and their meanings are defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FILENAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARIABLELIST"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>HOST_NOT_FOUND</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>No such host is known.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>NO_ADDRESS</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The server recognised the request and the name but no address is
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonavailable. Another type of request to the name server for the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssondomain might return an answer.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>A temporary and possibly transient error occurred, such as a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfailure of a server to respond. The request may succeed if
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>NO_RECOVERY</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>An unexpected failure occurred, and retrying the request
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis pointless.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_hstrerror</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontranslates these error codes to suitable error messages.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_gethostent</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getaddrinfo</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_getnameinfo</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CITEREFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRYTITLE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_hstrerror</SPAN