Technical Reference: Communications, Volume 2

gethostbyaddr Subroutine

Library

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

Syntax

#include <netdb.h>

struct hostent *gethostbyaddr ( Address, Length, Type) char *Address; int Length, Type;

Description

Attention: Do not use the gethostbyaddr subroutine in a multithreaded environment.

The gethostbyaddr subroutine retrieves information about a host using the host address as a search key. Unless specified, the gethostbyaddr subroutine uses the default name services ordering, that is, it will query DNS/BIND, NIS, then the local /etc/hosts file.

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

When using NIS for name resolution, if the getdomainname subroutine is successful and yp_bind indicates NIS is running, then the gethostbyaddr subroutine queries NIS.

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

The gethostbyaddr returns a pointer to a hostent structure, which contains information obtained from one of the name resolutions services. The hostent structure is defined in the netdb.h file.

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

Parameters

Address	Specifies a host address. The host address is passed as a pointer to the binary format address.
Length	Specifies the length of host address.
Type	Specifies the domain type of the host address. This currently works only on the address family AF_INET.

Return Values

The gethostbyaddr subroutine returns a pointer to a hostent structure upon success.

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

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

Error Codes

The gethostbyaddr subroutine is unsuccessful if any of the following errors occur:

HOST_NOT_FOUND	The host specified by the Name parameter is not found.
TRY_AGAIN	The local server does not receive a response from an authoritative server. Try again later.
NO_RECOVERY	This error code indicates an unrecoverable error.
NO_ADDRESS	The requested Address parameter is valid but does not have a name at the name server.
SERVICE_UNAVAILABLE	None of the name services specified are running or available.

Implementation Specifics

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

Files

/etc/hosts
	Contains the host-name database.
/etc/resolv.conf
	Contains the name server and domain name information.
/etc/netsvc.conf	Contains the name of the services ording.
/usr/include/netdb.h	Contains the network database structure.

Related Information

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

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