gethostbyaddr, gethostbyname, sethostent, endhostent
Purpose
Gets network host entry.
Library
Sockets Library (libsock.a)
Syntax
#include <netdb.h>
struct hostent *gethostbyaddr (addr, len, void)sethostent (stayopen)
char *addr; int stayopen;
int len, type;
void endhostent ( )
struct hostent *gethostbyname (name)
char *name;
Description
The gethostbyname and gethostbyaddr subroutines return a
pointer to an object. This object is a hostent struc-
ture, which contains information obtained from a name
server program, or contains a field from a line in the
/etc/hosts file (the network host data base).
The gethostbyname subroutine recognizes either domain
name servers (as described in RFC883) or IEN116 name
servers. (The details of these name servers are con-
tained in publications listed in "Related Network Publi-
cations.") If the file /etc/resolv.conf exists, a domain
name server is assumed by gethostbyname. (See the dis-
cussion of this file in Interface Program for use with
TCP/IP for more information.) If /etc/resolv.conf does
not exist, an IEN116 name server is assumed.
When a domain name server is used and the server request
times out, the local /etc/hosts file is checked. When an
IEN116 name server is used, the /etc/hosts file is
checked before the server is queried. Note that the
gethostbyaddr subroutine can only use a domain name
server.
The hostent structure is defined in the netdb.h header
file, and it contains the following members:
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 */
#define h_addr h_addr_list[0] /* address, for backward compatibility */
The members of the structure are defined below:
h_name Official name of the host.
h_aliases An array, terminated with a 0, of alternate
names for the host.
h_addrtype The type of address being returned. The
subroutine always sets this value to
AF_INET.
h_length The length of the address in bytes.
h_addr_list An array, terminated by a 0, of pointers to
the network addresses for the host. Host
addresses are returned in network byte
order.
h_addr The first address in h_addr_list, provided
for backward compatibility.
The sethostent subroutine opens and rewinds the file. If
the stayopen parameter is 0, the host data base is closed
after each call to the gethostbyname or gethostbyaddr
subroutines. Otherwise, the file is not closed after
each call.
The endhostent subroutine closes the file.
The gethostbyname and gethostbyaddr subroutines query the
name server or search the file sequentially from its
beginning until finding a matching host name or host
address, or until encountering the end of the file. Host
addresses are supplied in network order.
Return Value
The gethostbyname and gethostbyaddr subroutines return a
pointer to a hostent structure on success.
Note: The return value points to static data that is
overwritten by subsequent calls.
A NULL pointer (0) is returned if an error occurs or if
the end of the file is reached, and the h_errno variable
is set to indicate the error.
Diagnostics
The gethostbyname and gethostbyaddr subroutines fail if
one or more of the following are true:
HOST_NOT_FOUND The host specified by the name parameter
was not found.
TRY_AGAIN The local server did not receive a
response from an authoritative server.
Try again later.
NO_RECOVERY This error code indicates an unrecover-
able error.
NO_ADDRESS The requested name is valid but does not
have an Internet address at the name
server.
File
/etc/hosts Host name data base.
/etc/resolv.conf Name server and domain name data base.
Related Information
In this book: "Related Network Publications."
The discussion of /etc/hosts and /etc/resolv.conf in
Interface Program for use with TCP/IP.