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

Technical Reference: Communications, Volume 2

gethostbyaddr Subroutine


Gets network host entry by address.


Standard C Library (libc.a)


#include <netdb.h>

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


The gethostbyaddr 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 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.


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.

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:

Error Description
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.


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

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