diff options
Diffstat (limited to 'contrib/bind9/lib/lwres/man/lwres_gethostent.html')
| -rw-r--r-- | contrib/bind9/lib/lwres/man/lwres_gethostent.html | 784 |
1 files changed, 784 insertions, 0 deletions
diff --git a/contrib/bind9/lib/lwres/man/lwres_gethostent.html b/contrib/bind9/lib/lwres/man/lwres_gethostent.html new file mode 100644 index 000000000000..00b285db2061 --- /dev/null +++ b/contrib/bind9/lib/lwres/man/lwres_gethostent.html @@ -0,0 +1,784 @@ +<!-- + - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 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 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_gethostent.html,v 1.8.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_gethostent</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_gethostent</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 -- lightweight resolver get network host entry</DIV +><DIV +CLASS="REFSYNOPSISDIV" +><A +NAME="AEN21" +></A +><H2 +>Synopsis</H2 +><DIV +CLASS="FUNCSYNOPSIS" +><P +></P +><A +NAME="AEN22" +></A +><PRE +CLASS="FUNCSYNOPSISINFO" +>#include <lwres/netdb.h></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" +><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 — +<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 +>For backward compatibility with very old software, +<CODE +CLASS="CONSTANT" +>h_addr</CODE +> +is the first address in +<CODE +CLASS="CONSTANT" +>h_addr_list.</CODE +></P +><P +><CODE +CLASS="FUNCTION" +>lwres_gethostent()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_sethostent()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_endhostent()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_gethostent_r()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_sethostent_r()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_endhostent_r()</CODE +> +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 +><CODE +CLASS="FUNCTION" +>lwres_gethostbyname()</CODE +> and +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname2()</CODE +> look up the hostname +<VAR +CLASS="PARAMETER" +>name</VAR +>. +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname()</CODE +> always looks for an IPv4 +address while <CODE +CLASS="FUNCTION" +>lwres_gethostbyname2()</CODE +> looks for an +address of protocol family <VAR +CLASS="PARAMETER" +>af</VAR +>: either +<SPAN +CLASS="TYPE" +>PF_INET</SPAN +> or <SPAN +CLASS="TYPE" +>PF_INET6</SPAN +> — 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 +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname()</CODE +> or +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname2()</CODE +> fail.</P +><P +>Reverse lookups of addresses are performed by +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr()</CODE +>. +<VAR +CLASS="PARAMETER" +>addr</VAR +> is an address of length +<VAR +CLASS="PARAMETER" +>len</VAR +> bytes and protocol family +<VAR +CLASS="PARAMETER" +>type</VAR +> — <SPAN +CLASS="TYPE" +>PF_INET</SPAN +> or +<SPAN +CLASS="TYPE" +>PF_INET6</SPAN +>. +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +> is a thread-safe function +for forward lookups. If an error occurs, an error code is returned in +<VAR +CLASS="PARAMETER" +>*error</VAR +>. +<VAR +CLASS="PARAMETER" +>resbuf</VAR +> is a pointer to a <SPAN +CLASS="TYPE" +>struct +hostent</SPAN +> which is initialised by a successful call to +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +> . +<VAR +CLASS="PARAMETER" +>buf</VAR +> is a buffer of length +<VAR +CLASS="PARAMETER" +>len</VAR +> bytes which is used to store the +<CODE +CLASS="CONSTANT" +>h_name</CODE +>, <CODE +CLASS="CONSTANT" +>h_aliases</CODE +>, and +<CODE +CLASS="CONSTANT" +>h_addr_list</CODE +> elements of the <SPAN +CLASS="TYPE" +>struct +hostent</SPAN +> returned in <VAR +CLASS="PARAMETER" +>resbuf</VAR +>. +Successful calls to <CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +> +return <VAR +CLASS="PARAMETER" +>resbuf</VAR +>, +which is a pointer to the <SPAN +CLASS="TYPE" +>struct hostent</SPAN +> it created.</P +><P +><CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +> is a thread-safe function +that performs a reverse lookup of address <VAR +CLASS="PARAMETER" +>addr</VAR +> +which is <VAR +CLASS="PARAMETER" +>len</VAR +> bytes long and is of protocol +family <VAR +CLASS="PARAMETER" +>type</VAR +> — <SPAN +CLASS="TYPE" +>PF_INET</SPAN +> or +<SPAN +CLASS="TYPE" +>PF_INET6</SPAN +>. If an error occurs, the error code is returned +in <VAR +CLASS="PARAMETER" +>*error</VAR +>. The other function parameters are +identical to those in <CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +>. +<VAR +CLASS="PARAMETER" +>resbuf</VAR +> is a pointer to a <SPAN +CLASS="TYPE" +>struct +hostent</SPAN +> which is initialised by a successful call to +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +>. +<VAR +CLASS="PARAMETER" +>buf</VAR +> is a buffer of length +<VAR +CLASS="PARAMETER" +>len</VAR +> bytes which is used to store the +<CODE +CLASS="CONSTANT" +>h_name</CODE +>, <CODE +CLASS="CONSTANT" +>h_aliases</CODE +>, and +<CODE +CLASS="CONSTANT" +>h_addr_list</CODE +> elements of the <SPAN +CLASS="TYPE" +>struct +hostent</SPAN +> returned in <VAR +CLASS="PARAMETER" +>resbuf</VAR +>. Successful +calls to <CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +> return +<VAR +CLASS="PARAMETER" +>resbuf</VAR +>, which is a pointer to the +<CODE +CLASS="FUNCTION" +>struct hostent()</CODE +> it created.</P +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN191" +></A +><H2 +>RETURN VALUES</H2 +><P +>The functions +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname2()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr()</CODE +>, +and +<CODE +CLASS="FUNCTION" +>lwres_gethostent()</CODE +> +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" +><lwres/netdb.h></TT +>: + +<P +></P +><DIV +CLASS="VARIABLELIST" +><DL +><DT +><CODE +CLASS="CONSTANT" +>HOST_NOT_FOUND</CODE +></DT +><DD +><P +>The host or address was not found.</P +></DD +><DT +><CODE +CLASS="CONSTANT" +>TRY_AGAIN</CODE +></DT +><DD +><P +>A recoverable error occurred, e.g., a timeout. +Retrying the lookup may succeed.</P +></DD +><DT +><CODE +CLASS="CONSTANT" +>NO_RECOVERY</CODE +></DT +><DD +><P +>A non-recoverable error occurred.</P +></DD +><DT +><CODE +CLASS="CONSTANT" +>NO_DATA</CODE +></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 +><CODE +CLASS="FUNCTION" +>lwres_gethostent()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_gethostent_r()</CODE +> +always return +<SPAN +CLASS="TYPE" +>NULL</SPAN +>.</P +><P +>Successful calls to <CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +> and +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +> return +<VAR +CLASS="PARAMETER" +>resbuf</VAR +>, 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 <VAR +CLASS="PARAMETER" +>buf</VAR +> +was too small to hold the list of addresses and names referenced by +the <CODE +CLASS="CONSTANT" +>h_name</CODE +>, <CODE +CLASS="CONSTANT" +>h_aliases</CODE +>, and +<CODE +CLASS="CONSTANT" +>h_addr_list</CODE +> elements of the <SPAN +CLASS="TYPE" +>struct +hostent</SPAN +>. If <VAR +CLASS="PARAMETER" +>buf</VAR +> was too small, both +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +> and +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +> 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 +><CODE +CLASS="FUNCTION" +>lwres_gethostbyname()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname2()</CODE +>, +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr()</CODE +> +and +<CODE +CLASS="FUNCTION" +>lwres_endhostent()</CODE +> +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 +<CODE +CLASS="FUNCTION" +>lwres_gethostbyname_r()</CODE +>, +and +<CODE +CLASS="FUNCTION" +>lwres_gethostbyaddr_r()</CODE +> +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 +> |