178 lines
6.4 KiB
HTML
178 lines
6.4 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>g_h_b_n(3)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>g_h_b_n(3)</H1>
|
|
<HR>
|
|
<PRE>
|
|
|
|
</PRE>
|
|
<H2>NAME</H2><PRE>
|
|
g_h_b_n, gethostbyname, gethostbyaddr, gethostent, sethostent,
|
|
endhostent, herror - get network host entry
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<STRONG>#include</STRONG> <STRONG><net/gen/netdb.h></STRONG>
|
|
|
|
<STRONG>extern</STRONG> <STRONG>int</STRONG> <STRONG>h_errno;</STRONG>
|
|
|
|
<STRONG>struct</STRONG> <STRONG>hostent</STRONG> <STRONG>*gethostbyname(name)</STRONG>
|
|
<STRONG>char</STRONG> <STRONG>*name;</STRONG>
|
|
|
|
<STRONG>struct</STRONG> <STRONG>hostent</STRONG> <STRONG>*gethostbyaddr(addr,</STRONG> <STRONG>len,</STRONG> <STRONG>type)</STRONG>
|
|
<STRONG>char</STRONG> <STRONG>*addr;</STRONG> <STRONG>int</STRONG> <STRONG>len,</STRONG> <STRONG>type;</STRONG>
|
|
|
|
<STRONG>struct</STRONG> <STRONG>hostent</STRONG> <STRONG>*gethostent()</STRONG>
|
|
|
|
<STRONG>sethostent(stayopen)</STRONG>
|
|
<STRONG>int</STRONG> <STRONG>stayopen;</STRONG>
|
|
|
|
<STRONG>endhostent()</STRONG>
|
|
|
|
<STRONG>herror(string)</STRONG>
|
|
<STRONG>char</STRONG> <STRONG>*string;</STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
<EM>Gethostbyname</EM> and <EM>gethostbyaddr</EM> each return a pointer to an object with
|
|
the following structure describing an internet host referenced by name or
|
|
by address, respectively. This structure contains either the information
|
|
obtained from the name server, <STRONG><A HREF="../man8/named.8.html">named(8)</A></STRONG>, or broken-out fields from a line
|
|
in /<EM>etc</EM>/<EM>hosts</EM>. If the local name server is not running these routines do
|
|
a lookup in /<EM>etc</EM>/<EM>hosts</EM>.
|
|
|
|
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 */
|
|
|
|
The members of this structure are:
|
|
|
|
h_name Official name of the host.
|
|
|
|
h_aliases A zero terminated array of alternate names for the host.
|
|
|
|
|
|
|
|
h_addrtype The type of address being returned; currently always
|
|
AF_INET.
|
|
|
|
h_length The length, in bytes, of the address.
|
|
|
|
h_addr_list A zero terminated array of network addresses for the host.
|
|
Host addresses are returned in network byte order.
|
|
|
|
h_addr The first address in h_addr_list; this is for backward
|
|
compatiblity.
|
|
|
|
When using the nameserver, <EM>gethostbyname</EM> will search for the named host
|
|
in the current domain and its parents unless the name ends in a dot. If
|
|
the name contains no dot, and if the environment variable
|
|
``HOSTALAIASES'' contains the name of an alias file, the alias file will
|
|
first be searched for an alias matching the input name. See <STRONG><A HREF="../man7/hostname.7.html">hostname(7)</A></STRONG>
|
|
for the domain search procedure and the alias file format.
|
|
|
|
<EM>Sethostent</EM> may be used to request the use of a connected TCP socket for
|
|
queries. If the <EM>stayopen</EM> flag is non-zero, this sets the option to send
|
|
all queries to the name server using TCP and to retain the connection
|
|
after each call to <EM>gethostbyname</EM> or <EM>gethostbyaddr</EM>. Otherwise, queries
|
|
are performed using UDP datagrams.
|
|
|
|
<EM>Endhostent</EM> closes the TCP connection.
|
|
|
|
|
|
</PRE>
|
|
<H2>DIAGNOSTICS</H2><PRE>
|
|
|
|
Error return status from <EM>gethostbyname</EM> and <EM>gethostbyaddr</EM> is indicated by
|
|
return of a null pointer. The external integer <EM>h</EM>_<EM>errno</EM> may then be
|
|
checked to see whether this is a temporary failure or an invalid or
|
|
unknown host. The routine <EM>herror</EM> can be used to print an error message
|
|
describing the failure. If its argument <EM>string</EM> is non-NULL, it is
|
|
printed, followed by a colon and a space. The error message is printed
|
|
with a trailing newline.
|
|
|
|
<EM>h</EM>_<EM>errno</EM> can have the following values:
|
|
|
|
HOST_NOT_FOUND No such host is known.
|
|
|
|
TRY_AGAIN This is usually a temporary error and means that the
|
|
local server did not receive a response from an
|
|
authoritative server. A retry at some later time may
|
|
succeed.
|
|
|
|
NO_RECOVERY Some unexpected server failure was encountered. This is
|
|
a non-recoverable error.
|
|
|
|
|
|
|
|
NO_DATA The requested name is valid but does not have an IP
|
|
address; this is not a temporary error. This means that
|
|
the name is known to the name server but there is no
|
|
address associated with this name. Another type of
|
|
request to the name server using this domain name will
|
|
result in an answer; for example, a mail-forwarder may be
|
|
registered for this domain.
|
|
|
|
|
|
</PRE>
|
|
<H2>FILES</H2><PRE>
|
|
/etc/hosts
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<STRONG><A HREF="../man3/resolver.3.html">resolver(3)</A></STRONG>, <STRONG><A HREF="../man5/hosts.5.html">hosts(5)</A></STRONG>, <STRONG><A HREF="../man7/hostname.7.html">hostname(7)</A></STRONG>, <STRONG><A HREF="../man8/named.8.html">named(8)</A></STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>CAVEAT</H2><PRE>
|
|
|
|
<EM>Gethostent</EM> is defined, and <EM>sethostent</EM> and <EM>endhostent</EM> are redefined, when
|
|
<EM>libc</EM> is built to use only the routines to lookup in /<EM>etc</EM>/<EM>hosts</EM> and not
|
|
the name server.
|
|
|
|
<EM>Gethostent</EM> reads the next line of /<EM>etc</EM>/<EM>hosts</EM>, opening the file if
|
|
necessary.
|
|
|
|
<EM>Sethostent</EM> is redefined to open and rewind the file. If the <EM>stayopen</EM>
|
|
argument is non-zero, the hosts data base will not be closed after each
|
|
call to <EM>gethostbyname</EM> or <EM>gethostbyaddr</EM>. <EM>Endhostent</EM> is redefined to close
|
|
the file.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
All information is contained in a static area so it must be copied if it
|
|
is to be saved. Only the Internet address format is currently
|
|
understood.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|