<!--
- Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
- Copyright (C) 2001, 2003 Internet Software Consortium.
-
- Permission to use, copy, modify, and distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
- AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
- OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
- PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_getipnode.html,v 1.7.2.1.4.2 2004/08/22 23:39:04 marka Exp $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>lwres_getipnode</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
></A
>lwres_getipnode</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8"
></A
><H2
>Name</H2
>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN13"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN14"
></A
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include <lwres/netdb.h></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
><CODE
CLASS="CONSTANT"
>h_name</CODE
></DT
><DD
><P
>The official (canonical) name of the host.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_aliases</CODE
></DT
><DD
><P
>A NULL-terminated array of alternate names (nicknames) for the host.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_addrtype</CODE
></DT
><DD
><P
>The type of address being returned - usually
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>. </P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_length</CODE
></DT
><DD
><P
>The length of the address in bytes.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>h_addr_list</CODE
></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
><CODE
CLASS="FUNCTION"
>lwres_getipnodebyname()</CODE
>
looks up addresses of protocol family
<VAR
CLASS="PARAMETER"
>af</VAR
>
for the hostname
<VAR
CLASS="PARAMETER"
>name</VAR
>.
The
<VAR
CLASS="PARAMETER"
>flags</VAR
>
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
><CODE
CLASS="CONSTANT"
>AI_V4MAPPED</CODE
></DT
><DD
><P
>This is used with an
<VAR
CLASS="PARAMETER"
>af</VAR
>
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>AI_ALL</CODE
></DT
><DD
><P
>This is used with an
<VAR
CLASS="PARAMETER"
>af</VAR
>
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
><CODE
CLASS="CONSTANT"
>AI_ADDRCONFIG</CODE
></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
><CODE
CLASS="CONSTANT"
>AI_DEFAULT</CODE
></DT
><DD
><P
>This default sets the
<CODE
CLASS="CONSTANT"
>AI_V4MAPPED</CODE
>
and
<CODE
CLASS="CONSTANT"
>AI_ADDRCONFIG</CODE
>
flag bits.</P
></DD
></DL
></DIV
></P
><P
><CODE
CLASS="FUNCTION"
>lwres_getipnodebyaddr()</CODE
>
performs a reverse lookup
of address
<VAR
CLASS="PARAMETER"
>src</VAR
>
which is
<VAR
CLASS="PARAMETER"
>len</VAR
>
bytes long.
<VAR
CLASS="PARAMETER"
>af</VAR
>
denotes the protocol family, typically
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>. </P
><P
><CODE
CLASS="FUNCTION"
>lwres_freehostent()</CODE
>
releases all the memory associated with
the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
pointer
<VAR
CLASS="PARAMETER"
>he</VAR
>.
Any memory allocated for the
<CODE
CLASS="CONSTANT"
>h_name</CODE
>,
<CODE
CLASS="CONSTANT"
>h_addr_list</CODE
>
and
<CODE
CLASS="CONSTANT"
>h_aliases</CODE
>
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,
<CODE
CLASS="FUNCTION"
>lwres_getipnodebyname()</CODE
>
and
<CODE
CLASS="FUNCTION"
>lwres_getipnodebyaddr()</CODE
>
set
<VAR
CLASS="PARAMETER"
>*error_num</VAR
>
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"
><lwres/netdb.h></TT
>:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="CONSTANT"
>HOST_NOT_FOUND</CODE
></DT
><DD
><P
>No such host is known.</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>NO_ADDRESS</CODE
></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
><CODE
CLASS="CONSTANT"
>TRY_AGAIN</CODE
></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
><CODE
CLASS="CONSTANT"
>NO_RECOVERY</CODE
></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
>
