Technical Reference: Communications, Volume 2

gethostbyname Subroutine

Library

Standard C Library (libc.a)
(libbind)
(libnis)
(liblocal)

Syntax

#include <netdb.h>

struct hostent *gethostbyname ( Name) char *Name;

Description

Note:The gethostbyname subroutine is threadsafe in AIX 4.3.

The gethostbyname subroutine retrieves host address and name information using a host name as a search key. Unless specified, the gethostbyname subroutine uses the default name services ordering, that is, it queries DNS/BIND, NIS or the local /etc/hosts file for the name.

When using DNS/BIND name service resolution, if the /etc/resolv.conf file exists, the gethostbyname subroutine queries the domain name server. The gethostbyname subroutine recognizes domain name servers as described in RFC883.

When using NIS for name resolution, if the getdomaninname subroutine is successful and yp_bind indicates yellow pages are running, then the gethostbyname subroutine queries NIS for the name.

The gethostbyname subroutine also searches the local /etc/hosts file for the name when indicated to do so.

The gethostbyname subroutine returns a pointer to a hostent structure, which contains information obtained from a name resolution services. The hostent structure is defined in the netdb.h header file.

Parameters

Name

Points to the host name.

Return Values

The gethostbyname subroutine returns a pointer to a hostent structure on success.

Note: The return value points to static data that is overwritten by subsequent calls so it must be copied it it is to be saved.

If the parameter Name passed to gethostbyname is actually an IP address, gethostbyname will return a non-NULL hostent structure with an IP address as the hostname without actually doing a lookup. Remember to call inet_addr subroutine to make sure Name is not an IP address before calling gethostbyname. To resolve an IP address call gethostbyaddr instead.

If an error occurs or if the end of the file is reached, the gethostbyname subroutine returns a null pointer and sets h_errno to indicate the error.

The environment variable, NSORDER can be set to overide the default name services ordering and the order specified in the /etc/netsvc.conf file.

By default, resolver routines first attempt to resolve names through the DNS/BIND, then NIS and the /etc/hosts file. The /etc/netsvc.conf file may specify a different search order. The environment variable NSORDER overrides both the /etc/netsvc.conf file and the default ordering. Services are ordered as hosts = value, value, value in the /etc/netsvc.conf file where at least one value must be specified from the list bind, nis, local. NSORDER specifies a list of values.

Error Codes

The gethostbyname subroutine is unsuccessful if any of the following errors occurs:

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 unrecoverable error.
NO_ADDRESS	The requested Name is valid but does not have an Internet address at the name server.
SERVICE_UNAVAILABLE	None of the name services specified are running or available.

Examples

The following program fragment illustrates the use of the gethostbyname subroutine to look up a destination host:

hp=gethostbyname(argv[1]);
if(hp = = NULL) {
          fprintf(stderr, "rlogin: %s: unknown host\n", argv[1]);
          exit(2);
}

Implementation Specifics

The gethostbyname subroutine is part of Base Operating System (BOS) Runtime.

Files

/etc/hosts	Contains the host name data base.
/etc/resolv.conf	Contains the name server and domain name.
/etc/netsvc.conf	Contains the name services ordering.
/usr/include/netdb.h	Contains the network database structure.

Related Information

The endhostent subroutine, gethostbyaddr subroutine, gethostent subroutine, sethostent subroutine, inet_addr subroutine.

Sockets Overview and Network Address Translation in AIX 5L Version 5.1 Communications Programming Concepts.