lwres_getipnode.html revision 3970098dcd2a7122541667b4b56cea8abce8ccf2
70N/A<!--
70N/A - Copyright (C) 2000, 2001 Internet Software Consortium.
70N/A -
70N/A - Permission to use, copy, modify, and distribute this software for any
911N/A - purpose with or without fee is hereby granted, provided that the above
851N/A - copyright notice and this permission notice appear in all copies.
70N/A -
70N/A - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
919N/A - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
919N/A - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
919N/A - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
919N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
919N/A - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
919N/A - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
919N/A - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
919N/A-->
919N/A<HTML
919N/A><HEAD
919N/A><TITLE
919N/A>lwres_getipnode</TITLE
919N/A><META
919N/ANAME="GENERATOR"
919N/ACONTENT="Modular DocBook HTML Stylesheet Version 1.73
919N/A"></HEAD
919N/A><BODY
70N/ACLASS="REFENTRY"
70N/ABGCOLOR="#FFFFFF"
70N/ATEXT="#000000"
70N/ALINK="#0000FF"
493N/AVLINK="#840084"
70N/AALINK="#0000FF"
70N/A><H1
851N/A><A
70N/ANAME="AEN1"
911N/A>lwres_getipnode</A
911N/A></H1
911N/A><DIV
911N/ACLASS="REFNAMEDIV"
70N/A><A
70N/ANAME="AEN8"
70N/A></A
70N/A><H2
70N/A>Name</H2
70N/A>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent&nbsp;--&nbsp;lightweight resolver nodename / address translation API</DIV
70N/A><DIV
70N/ACLASS="REFSYNOPSISDIV"
70N/A><A
493N/ANAME="AEN13"
70N/A></A
70N/A><H2
493N/A>Synopsis</H2
70N/A><DIV
70N/ACLASS="FUNCSYNOPSIS"
70N/A><A
70N/ANAME="AEN14"
70N/A></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;lwres/netdb.h&gt;</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_getipnodebyname</CODE
>(const char *name, int af, int flags, int *error_num);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_getipnodebyaddr</CODE
>(const void *src, size_t len, int af, int *error_num);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_freehostent</CODE
>(struct hostent *he);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN34"
></A
><H2
>DESCRIPTION</H2
><P
>These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.</P
><P
>They use a
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
which is defined in
<TT
CLASS="FILENAME"
>namedb.h</TT
>:
<PRE
CLASS="PROGRAMLISTING"
>struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses from name server */
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */</PRE
></P
><P
>The members of this structure are:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="CONSTANT"
>h_name</TT
></DT
><DD
><P
>The official (canonical) name of the host.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>h_aliases</TT
></DT
><DD
><P
>A NULL-terminated array of alternate names (nicknames) for the host.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>h_addrtype</TT
></DT
><DD
><P
>The type of address being returned - usually
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.&#13;</P
></DD
><DT
><TT
CLASS="CONSTANT"
>h_length</TT
></DT
><DD
><P
>The length of the address in bytes.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>h_addr_list</TT
></DT
><DD
><P
>A
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
terminated array of network addresses for the host.
Host addresses are returned in network byte order.</P
></DD
></DL
></DIV
></P
><P
><TT
CLASS="FUNCTION"
>lwres_getipnodebyname()</TT
>
looks up addresses of protocol family
<TT
CLASS="PARAMETER"
><I
>af</I
></TT
>
for the hostname
<TT
CLASS="PARAMETER"
><I
>name</I
></TT
>.
The
<TT
CLASS="PARAMETER"
><I
>flags</I
></TT
>
parameter contains ORed flag bits to
specify the types of addresses that are searched
for, and the types of addresses that are returned.
The flag bits are:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="CONSTANT"
>AI_V4MAPPED</TT
></DT
><DD
><P
>This is used with an
<TT
CLASS="PARAMETER"
><I
>af</I
></TT
>
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>AI_ALL</TT
></DT
><DD
><P
>This is used with an
<TT
CLASS="PARAMETER"
><I
>af</I
></TT
>
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
IPv6 addresses.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>AI_ADDRCONFIG</TT
></DT
><DD
><P
>Only return an IPv6 or IPv4 address if here is an active network
interface of that type. This is not currently implemented
in the BIND 9 lightweight resolver, and the flag is ignored.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>AI_DEFAULT</TT
></DT
><DD
><P
>This default sets the
<TT
CLASS="CONSTANT"
>AI_V4MAPPED</TT
>
and
<TT
CLASS="CONSTANT"
>AI_ADDRCONFIG</TT
>
flag bits.</P
></DD
></DL
></DIV
></P
><P
><TT
CLASS="FUNCTION"
>lwres_getipnodebyaddr()</TT
>
performs a reverse lookup
of address
<TT
CLASS="PARAMETER"
><I
>src</I
></TT
>
which is
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes long.
<TT
CLASS="PARAMETER"
><I
>af</I
></TT
>
denotes the protocol family, typically
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.&#13;</P
><P
><TT
CLASS="FUNCTION"
>lwres_freehostent()</TT
>
releases all the memory associated with
the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
pointer
<TT
CLASS="PARAMETER"
><I
>he</I
></TT
>.
Any memory allocated for the
<TT
CLASS="CONSTANT"
>h_name</TT
>,
<TT
CLASS="CONSTANT"
>h_addr_list</TT
>
and
<TT
CLASS="CONSTANT"
>h_aliases</TT
>
is freed, as is the memory for the
<SPAN
CLASS="TYPE"
>hostent</SPAN
>
structure itself.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN116"
></A
><H2
>RETURN VALUES</H2
><P
>If an error occurs,
<TT
CLASS="FUNCTION"
>lwres_getipnodebyname()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_getipnodebyaddr()</TT
>
set
<TT
CLASS="PARAMETER"
><I
>*error_num</I
></TT
>
to an appropriate error code and the function returns a
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
pointer.
The error codes and their meanings are defined in
<TT
CLASS="FILENAME"
>&lt;lwres/netdb.h&gt;</TT
>:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="CONSTANT"
>HOST_NOT_FOUND</TT
></DT
><DD
><P
>No such host is known.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>NO_ADDRESS</TT
></DT
><DD
><P
>The server recognised the request and the name but no address is
available. Another type of request to the name server for the
domain might return an answer.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>TRY_AGAIN</TT
></DT
><DD
><P
>A temporary and possibly transient error occurred, such as a
failure of a server to respond. The request may succeed if
retried.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>NO_RECOVERY</TT
></DT
><DD
><P
>An unexpected failure occurred, and retrying the request
is pointless.</P
></DD
></DL
></DIV
></P
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_hstrerror</SPAN
>(3)</SPAN
>
translates these error codes to suitable error messages.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN149"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>RFC2553</SPAN
></SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_gethostent</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_getaddrinfo</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_getnameinfo</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_hstrerror</SPAN
>(3)</SPAN
>.</P
></DIV
></BODY
></HTML
>