[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Communications, Volume 2

gethostbyname Subroutine

Purpose

Gets network host entry by name.

Library

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

Syntax


#include <netdb.h>

struct hostent *gethostbyname ( Name)
char *Name;

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

Name Points to the host name.

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:

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

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.2 Communications Programming Concepts.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]