gethostbyname(3N)

NAME

__order_init, gethostbyname, gethostbyaddr, sethostent, endhostent − get network host entry

SYNOPSIS

#include <netdb.h>

extern int h_errno;

void __order_init(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 contains either the information obtained from the DARPA Internet Domain Name System (DNS) resolver (resolver(3N)), information obtained from the Yellow Pages server, ypserv(1M), or broken-out fields from a line in /etc/hosts.

structhostent {
char∗h_name;/∗ official name of host ∗/
char∗∗h_aliases;/∗ alias list ∗/
inth_addrtype;/∗ host address type ∗/
inth_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.

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 __order_init 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 specified 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 performed regardless of whether it has been performed before. Both gethostbyname and gethostbyaddr call __order_init 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 bcs_cat(1) and bcs_match(1). These commands provide access to Yellow Pages services on the system. For 88open OCSNS compliant applications, both gethostbyname and gethostbyaddr check for the existence of either comand and take approrpiate action. If the file /etc/bcs_match 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/bcs_match cannot be executed, and /etc/bcs_cat exists and has the correct execute permission, the command /etc/bcs_cat 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 converted 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 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:

HOST_NOT_FOUNDNo such host is known.

TRY_AGAINThis 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_RECOVERYThis is a non-recoverable error.

NO_ADDRESSThe 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 Support). Accordingly, systems connected to the Internet must edit /etc/svcorder to ensure the DNS resolver is used.

FILES

/etc/hostsHosts file database
/etc/svcorderResolution methods database

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.

CX/UX Networking

Museum

Related Articles