gethostent(3N)
gethostent --
get network host entry
Synopsis
cc [options] file -lsocket -lnsl
#include <netdb.h>
extern int h_errno;
struct hostent *gethostent(void);
struct hostent *gethostbyname(const char *name);
struct hostent *gethostbyname2(const char *name, int af);
struct hostent *gethostbyaddr(const void *addr, size_t len, int type);
void sethostent(int stayopen);
void endhostent(void)
Description
gethostent reads a line from /etc/hosts,
opening the file if necessary.
It returns a pointer to a structure of type hostent
which describes an internet host.
sethostent allows gethostent to read
subsequent lines from /etc/hosts.
If the stayopen argument is non-zero, the hosts'
database will not be closed after each call to gethostent.
sethostent opens
a connected TCP socket for queries, and retains the
connection after each call to gethostent.
If stayopen is zero,
queries are performed using UDP datagrams and
the file is re-opened (and rewound) on each invocation
of gethostent.
endhostent closes the TCP connection.
gethostbyname, gethostbyname2 and gethostbyaddr
also return a pointer to a structure of type hostent
which describes an internet host.
These routines search for this description, by hostname, hostname and
address family or by host address, respectively, in any or all of the following
databases:
the Domain Name System (DNS),
the Network Information Service (NIS),
and the file /etc/hosts.
NOTE:
For gethostbyname2, use the af argument to specify the
address family. Valid address families are AF_INET (IP
version 4) and AF_INET6 (IP version 6). If you do
not specify a valid address family, this function returns NULL,
and sets h_errno to NETDB_INTERNAL.
gethostbyname assumes AF_INET by default.
The order and number of databases searched depends on the order given for
the libraries in the ``directory lookup libraries'' field of the
entries for the tcp, udp, icmp,
rawip, igmp, tcp6, udp6,
icmpv6 and rawipv6 services
in the network configuration database, /etc/netconfig (see
netconfig(4bnu)).
NOTE:
These routines do not read /etc/netconfig directly.
They invoke the resolver routine res_init (see
resolver(3N)).
The hostent structure is defined as follows:
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 null-terminated array of alternate names for the host.
h_addrtype
-
The type of address being returned; currently either AF_INET or
AF_INET6.
h_length
-
The length, in bytes, of the address.
h_addr_list
-
A null-terminated array of network addresses for the host.
Host addresses are returned in network byte order in
struct in_addr for AF_INET and
struct in6_addr for AF_INET6.
h_addr
-
The first address in
h_addr_list
;
this is for backward compatibility.
When using the name server,
gethostbyname and gethostbyname2
search for the named host in the current domain and then its parents,
unless the name ends in a dot.
If the name contains no dot, and if the environment
variable HOSTALIASES contains the name of
an alias file, the alias file is first searched
for an alias matching the input name.
See
hostname(1bsd)
for the domain search procedure and the alias file format.
Files
/etc/hosts
/etc/netconfig
Diagnostics
Error return status from gethostbyname,
gethostbyname2 and gethostbyaddr
is indicated by return of a null pointer.
The external integer h_errno
may then be checked to see whether this is a temporary failure
or an invalid or unknown host.
h_errno can have the following values:
NETDB_INTERNAL-
This indicates an internal error in the library, unrelated
to the network or name service. errno is valid
in this case.
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.
References
getaddrinfo(3N),
getnameinfo(3N),
hosts(4tcp),
hostname(1bsd),
named(1Mtcp),
netconfig(4bnu),
resolver(3N)
Notices
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.
Standards compliance
gethostbyname, gethostbyname2
and gethostbyaddr are conformant with:
RFC1034 (STD13), RFC1035 (STD13)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004