ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity
Files
b994e16d9d3d73893b4e21e8464c8d26530cb2a6
bind9/lib/lwres/man/lwres_gethostent.html
Andreas Gustafsson 841179549b 889. [port] Eliminated blank lines before .TH in nroff man 
pages since they cause problems with some versions
                        of nroff. [RT #1390]
2001-06-08 19:33:02 +00:00

921 lines
12 KiB
HTML
Raw Blame History

<!--
- Copyright (C) 2000, 2001 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 INTERNET SOFTWARE CONSORTIUM
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
- INTERNET SOFTWARE CONSORTIUM 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_gethostent.html,v 1.6 2001/06/08 19:32:33 gson Exp $ -->
<HTML
><HEAD
><TITLE
>lwres_gethostent</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
>lwres_gethostent</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8"
></A
><H2
>Name</H2
>lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r&nbsp;--&nbsp;lightweight resolver get network host entry</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN21"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN22"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;lwres/netdb.h&gt;</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostbyname</CODE
>(const char *name);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostbyname2</CODE
>(const char *name, int af);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostbyaddr</CODE
>(const char *addr, int len, int type);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostent</CODE
>(void);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_sethostent</CODE
>(int stayopen);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_endhostent</CODE
>(void);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostbyname_r</CODE
>(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostbyaddr_r</CODE
>(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>struct hostent *
lwres_gethostent_r</CODE
>(struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_sethostent_r</CODE
>(int stayopen);</CODE
></P
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void
lwres_endhostent_r</CODE
>(void);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN84"
></A
><H2
>DESCRIPTION</H2
><P
>These functions provide hostname-to-address and
address-to-hostname lookups by means of the lightweight resolver.
They are similar to the standard
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>gethostent</SPAN
>(3)</SPAN
>
functions provided by most operating systems.
They use a
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
which is usually defined in
<TT
CLASS="FILENAME"
>&lt;namedb.h&gt;</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 &mdash;
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.</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
>For backward compatibility with very old software,
<TT
CLASS="CONSTANT"
>h_addr</TT
>
is the first address in
<TT
CLASS="CONSTANT"
>h_addr_list.</TT
></P
><P
><TT
CLASS="FUNCTION"
>lwres_gethostent()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_sethostent()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_endhostent()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_gethostent_r()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_sethostent_r()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_endhostent_r()</TT
>
provide iteration over the known host entries on systems that
provide such functionality through facilities like
<TT
CLASS="FILENAME"
>/etc/hosts</TT
>
or NIS. The lightweight resolver does not currently implement
these functions; it only provides them as stub functions that always
return failure.</P
><P
><TT
CLASS="FUNCTION"
>lwres_gethostbyname()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_gethostbyname2()</TT
>
look up the hostname
<TT
CLASS="PARAMETER"
><I
>name</I
></TT
>.
<TT
CLASS="FUNCTION"
>lwres_gethostbyname()</TT
>
always looks for an IPv4 address while
<TT
CLASS="FUNCTION"
>lwres_gethostbyname2()</TT
>
looks for an address of protocol family
<TT
CLASS="PARAMETER"
><I
>af</I
></TT
>:
either
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>
&mdash; IPv4 or IPV6 addresses respectively.
Successful calls of the functions return a
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>for
the name that was looked up.
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
is returned if the lookups by
<TT
CLASS="FUNCTION"
>lwres_gethostbyname()</TT
>
or
<TT
CLASS="FUNCTION"
>lwres_gethostbyname2()</TT
>
fail.</P
><P
>Reverse lookups of addresses are performed by
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr()</TT
>.
<TT
CLASS="PARAMETER"
><I
>addr</I
></TT
>
is an address of length
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes and protocol family
<TT
CLASS="PARAMETER"
><I
>type</I
></TT
> &mdash;
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>
is a thread-safe function for forward lookups.
If an error occurs, an error code is returned in
<TT
CLASS="PARAMETER"
><I
>*error</I
></TT
>.
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>
is a pointer to a
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
which is initialised by a successful call to
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
> .
<TT
CLASS="PARAMETER"
><I
>buf</I
></TT
>
is a buffer of length
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes which is used to store the
<TT
CLASS="CONSTANT"
>h_name</TT
>,
<TT
CLASS="CONSTANT"
>h_aliases</TT
>,
and
<TT
CLASS="CONSTANT"
>h_addr_list</TT
>
elements of the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
returned in
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>.
Successful calls to
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>
return
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>,
which is a pointer to the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
it created.</P
><P
><TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>
is a thread-safe function that performs a reverse lookup of address
<TT
CLASS="PARAMETER"
><I
>addr</I
></TT
>
which is
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes long
and is of protocol family
<TT
CLASS="PARAMETER"
><I
>type</I
></TT
> &mdash;
<SPAN
CLASS="TYPE"
>PF_INET</SPAN
>
or
<SPAN
CLASS="TYPE"
>PF_INET6</SPAN
>.
If an error occurs, the error code is returned in
<TT
CLASS="PARAMETER"
><I
>*error</I
></TT
>.
The other function parameters are identical to those in
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>.
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>
is a pointer to a
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
which is initialised by a successful call to
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>.
<TT
CLASS="PARAMETER"
><I
>buf</I
></TT
>
is a buffer of length
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
bytes which is used to store the
<TT
CLASS="CONSTANT"
>h_name</TT
>,
<TT
CLASS="CONSTANT"
>h_aliases</TT
>,
and
<TT
CLASS="CONSTANT"
>h_addr_list</TT
>
elements of the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
returned in
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>.
Successful calls to
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>
return
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>,
which is a pointer to the
<TT
CLASS="FUNCTION"
>struct hostent()</TT
>
it created.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN191"
></A
><H2
>RETURN VALUES</H2
><P
>The functions
<TT
CLASS="FUNCTION"
>lwres_gethostbyname()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_gethostbyname2()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr()</TT
>,
and
<TT
CLASS="FUNCTION"
>lwres_gethostent()</TT
>
return NULL to indicate an error. In this case the global variable
<SPAN
CLASS="TYPE"
>lwres_h_errno</SPAN
>
will contain one of the following error codes 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
>The host or address was not found.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>TRY_AGAIN</TT
></DT
><DD
><P
>A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>NO_RECOVERY</TT
></DT
><DD
><P
>A non-recoverable error occurred.</P
></DD
><DT
><TT
CLASS="CONSTANT"
>NO_DATA</TT
></DT
><DD
><P
>The name exists, but has no address information
associated with it (or vice versa in the case
of a reverse lookup). The code NO_ADDRESS
is accepted as a synonym for NO_DATA for backwards
compatibility.</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
><P
><TT
CLASS="FUNCTION"
>lwres_gethostent()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_gethostent_r()</TT
>
always return
<SPAN
CLASS="TYPE"
>NULL</SPAN
>.&#13;</P
><P
>Successful calls to
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>
return
<TT
CLASS="PARAMETER"
><I
>resbuf</I
></TT
>,
a pointer to the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>
that was initialised by these functions.
They return
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
if the lookups fail
or if
<TT
CLASS="PARAMETER"
><I
>buf</I
></TT
>
was too small to hold the list of addresses and names referenced by
the
<TT
CLASS="CONSTANT"
>h_name</TT
>,
<TT
CLASS="CONSTANT"
>h_aliases</TT
>,
and
<TT
CLASS="CONSTANT"
>h_addr_list</TT
>
elements of the
<SPAN
CLASS="TYPE"
>struct hostent</SPAN
>.
If
<TT
CLASS="PARAMETER"
><I
>buf</I
></TT
>
was too small, both
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>
set the global variable
<SPAN
CLASS="TYPE"
>errno</SPAN
>
to
<SPAN
CLASS="ERRORCODE"
>ERANGE</SPAN
>.&#13;</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN245"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>gethostent</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_getipnode</SPAN
>(3)</SPAN
>,
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres_hstrerror</SPAN
>(3)</SPAN
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN257"
></A
><H2
>BUGS</H2
><P
><TT
CLASS="FUNCTION"
>lwres_gethostbyname()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_gethostbyname2()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr()</TT
>
and
<TT
CLASS="FUNCTION"
>lwres_endhostent()</TT
>
are not thread safe; they return pointers to static data and
provide error codes through a global variable.
Thread-safe versions for name and address lookup are provided by
<TT
CLASS="FUNCTION"
>lwres_gethostbyname_r()</TT
>,
and
<TT
CLASS="FUNCTION"
>lwres_gethostbyaddr_r()</TT
>
respectively.</P
><P
>The resolver daemon does not currently support any non-DNS
name services such as
<TT
CLASS="FILENAME"
>/etc/hosts</TT
>
or
<SPAN
CLASS="TYPE"
>NIS</SPAN
>,
consequently the above functions don't, either.</P
></DIV
></BODY
></HTML
>
View Git Blame Copy Permalink