ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity
Files
3ad4e307b64bcf8baa984e10a4e7549dbeaea31d
bind9/lib/lwres/man/lwres_gethostent.html
Andreas Gustafsson ac299c4f5c Removed statements to the effect that certain functions 
perform assertion checks.  Such statements are inappropriate as they
document the implementation rather than the public interface.  The
functions are not required to perform assertion checks, but the caller
is required to pass arguments that conform to the API requirements.
2001-06-18 22:56:35 +00:00

827 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.
-->
<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
>.</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
>.</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