gethostbyname(3N) gethostbyname(3N)
NAME
orderinit, gethostbyname, gethostbyaddr, sethostent,
endhostent - get network host entry
SYNOPSIS
#include <netdb.h>
extern int herrno;
void orderinit(key, force)
char *key; int force;
struct hostent *gethostbyname(name)
char *name;
struct hostent *gethostbyaddr(addr, len, type)
char *addr; int len, type;
sethostent(stayopen)
int stayopen;
endhostent()
DESCRIPTION
gethostbyname and gethostbyaddr each return a pointer to an
object with the following structure. This structure con-
tains either the information obtained from the DARPA Inter-
net Domain Name System (DNS) resolver (resolver(3N)), infor-
mation obtained from the Yellow Pages server, ypserv(1M), or
broken-out fields from a line in /etc/hosts.
struct hostent {
char *hname; /* official name of host */
char **haliases; /* alias list */
int haddrtype; /* host address type */
int hlength; /* length of address */
char **haddrlist;/* list of addresses from name server */
};
#define haddr haddrlist[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.
Page 1 CX/UX Networking
gethostbyname(3N) gethostbyname(3N)
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.
The file /etc/svcorder specifies the order in which the
methods outlined above are to be tried. If this file does
not exist or is not readable, the default order is to try
the Yellow Pages server first. If the Yellow Pages lookup
fails or Yellow Pages is not in use, a lookup in /etc/hosts
is done. For applications conforming to the 88open Object
Compatibility Standard Networking Supplement (OCSNS) the
default order is to try first Yellow Pages, then /etc/hosts,
and then the DNS resolver.
The orderinit function provides a means for applications
to initialize the order in which they desire to use the
lookup methods. The first parameter to this function points
to a sequence string of the form found in /etc/svcorder, and
described in svcorder(4C). If this parameter is NULL or it
contains only blanks (space, tab, newline), the order speci-
fied in /etc/svcorder or the default order will be used.
Under normal circumstances, this initialization is performed
once in the lifetime of a process. The second parameter, if
non-zero, specifies that the initialization is to be per-
formed regardless of whether it has been performed before.
Both gethostbyname and gethostbyaddr call orderinit with
a NULL first parameter and a zero second parameter, except
for 88open OCSNS compliant applications, when the second
parameter is non-zero. Invalid lookup methods in the key
are ignored. If the key contains no valid lookup methods
then all hostname lookups will fail until the order is re-
initialized.
The DNS resolver uses UDP as its transport by default. Due
to the nature of UDP, this is sometimes undesirable.
Sethostent, if the stayopen flag is non-zero, instructs the
DNS resolver to use a TCP connection for queries to the
nameserver, and to retain the connection after each call to
gethostbyname or gethostbyaddr. Otherwise, the DNS resolver
is instructed to use the default UDP.
Endhostent instructs the DNS resolver to use UDP, and closes
any lingering connections to the nameserver.
For 88open OCSNS compliant applications, "Yellow Pages" does
not refer directly to the NFS-oriented Yellow Pages, but
rather to the commands bcscat(1) and bcsmatch(1). These
commands provide access to Yellow Pages services on the sys-
tem. For 88open OCSNS compliant applications, both
Page 2 CX/UX Networking
gethostbyname(3N) gethostbyname(3N)
gethostbyname and gethostbyaddr check for the existence of
either comand and take approrpiate action. If the file
/etc/bcsmatch exists and has correct execute permission,
the command will be executed with appropriate parameters,
and its output interpreted and converted into a hostent
structure. If /etc/bcsmatch cannot be executed, and
/etc/bcscat exists and has the correct execute permission,
the command /etc/bcscat hosts is executed and its output
interpreted until a match is found or the output is
exhausted. If a match is found, the information is con-
verted into a hostent structure. If neither file can be
executed, the lookup is considered to have failed, and the
next lookup method configured is attempted.
DIAGNOSTICS
Error return status from gethostbyname and gethostbyaddr is
indicated by return of a null pointer. The external integer
herrno may then be checked to see whether this is a tem-
porary failure or an invalid or unknown host.
herrno 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 authorita-
tive server. A retry at some later
time may succeed.
NO_RECOVERY This is a non-recoverable error.
NO_ADDRESS The requested name is valid but does
not have an IP address; this is not a
temporary error. This means another
type of request to the name server will
result in an answer.
NOTES
The 88open OCSNS versions of the above files may be accessed
through special OCS options passed to cc(1) and/or ld(1).
The use of the DNS resolver is mandated by the Internet (RFC
1123 Requirements for Internet Hosts - Application and Sup-
port). Accordingly, systems connected to the Internet must
edit /etc/svcorder to ensure the DNS resolver is used.
FILES
/etc/hosts Hosts file database
/etc/svcorder Resolution methods database
Page 3 CX/UX Networking
gethostbyname(3N) gethostbyname(3N)
SEE ALSO
bcscat(1), bcsmatch(1), hosts(4C), resolver(3N),
svcorder(4C), ypserv(1M)
/usr/doc/rfc1123.lpr Requirements for Internet Hosts -
Application and Support
BUGS
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.
While both the DNS resolver and /etc/hosts file lookup
methods are case-insensitive, "Yellow Pages" is case-
sensitive.
Page 4 CX/UX Networking