getipnodebyaddr(3) — Subroutines

NAME

getipnodebyaddr − Gets a network host entry by address

LIBRARY

Standard C Library (libc.so, libc.a)

SYNOPSIS

#include <netdb.h>

struct hostent ∗getipnodebyaddr(
const void ∗src,
size_t len,
int af,
int ∗error_num);

PARAMETERS

srcSpecifies an Internet address in network order.

lenSpecifies the number of bytes in an Internet address.

afSpecifies the Internet domain address format. Valid values are AF_INET and AF_INET6.

error_numSpecifies an error return code value if the function is not successful. See the ERRORS section for a description of the values.

DESCRIPTION

The getipnodebyaddr() routine returns a pointer to a structure of type hostent. Its members specify data obtained from either the local /etc/hosts file or one of the files distributed by DNS/BIND or NIS. To determine which file or files to search, and in which order, the system uses the switches in the /etc/svc.conf file. The netdb.h header file defines the hostent structure.

The getipnodebyaddr() routine searches the network host database sequentially until a match with the src and af parameters occurs. The len parameter must specify the number of bytes in an Internet address. The src parameter must specify the address in network order. The af parameter can be either the constant AF_INET or AF_INET6, which specifies the Internet Protocol Version 4 (IPv4) address format or Internet Protocol Version 6 (IPv6) address format, respectively. When EOF (End-of-File) is reached without a match, an error value is returned.

If the src parameter is either an Internet Protocol Version 4 (IPv4) mapped IPv6 address or an IPv4-compatible IPv6 address, the routine performs the following steps in order:

1.If the af parameter is AF_INET6, the len parameter is 16, and the src parameter is either an IPV4-mapped IPv6 address or an IPv4-compatible IPv6 address, the routine skips the first 12 bytes of the address, sets af to AF_INET and len to 4.

2.If the af parameter is AF_INET, the routine queries for a PTR record in the in-addr.arpa domain.

3.If the af parameter is AF_INET6, the routine queries for a PTR record in the ip6.int domain.

4.If the routine returns success, the single address and address family returned in the hostent structure are copies of the src parameter and the af parameter, respectively, that were passed to the routine. The :: and ::1 IPv6 addresses are not considered IPv4-compatible addresses.

If using DNS/BIND, the information is obtained from a name server specified in the /etc/resolv.conf file. When the name server is not running, the getipnodebyaddr() routine searches the local hosts name file.

The getipnodebyaddr() routine dynamically allocates the hostent structure. Use the freehostent() routine to free the allocated memory.

EXAMPLES

1.For IPv4 applications (backward compatibility), use the following syntax:

getipnodebyaddr(address, 4, AF_INET, &error_num);

RETURN VALUES

Upon successful completion, the getipnodebyaddr() routine returns a pointer to a hostent structure. If it reaches the end of the network hostname database, it returns a null pointer.

ERRORS

If the getipnodebyaddr() routine call fails, error_num is set to one of the following values:

[HOST_NOT_FOUND]
Host is unknown.

[NO_DATA]The server recognized the request and the name, but no address is available for the name. Another type of name server request may be successful.

[NO_RECOVERY]
An unexpected server failure occurred. This is a nonrecoverable error.

[TRY_AGAIN]
A transient error occurred, for example, the server did not respond. A retry at some later time may be successful.

FILES

/etc/hostsThis file is the Internet network hostname database. Each record in the file occupies a single line and has three fields consisting of the host address, official hostname, and aliases.

/etc/resolv.conf
The resolver configuration file.

/etc/svc.conf
The database service selection configuration file.