gethostbyname Subroutine

Purpose

Gets network host entry by name.

Library

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

Syntax

Description

The gethostbyname subroutine is threadsafe in AIX® 4.3 and later. However, the return value points to static data that is overwritten by subsequent calls. This data must be copied to be saved for use by subsequent calls.

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

Return Values

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

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 occur:

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);
}

Files